@company-semantics/contracts 31.0.0 → 33.0.0

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

@@ -58,41 +58,45 @@ add("org.invite", "Admin", {
   orgName: "Acme Corp",
   role: "admin",
   acceptUrl: `${APP}/invite/abc123`,
-  expiresInDays: 7,
+  expiresAt: "2026-06-13T00:00:00.000Z",
 });
 add("org.invite", "Member", {
   inviterName: "Alex Rivera",
   orgName: "Acme Corp",
   role: "member",
   acceptUrl: `${APP}/invite/def456`,
-  expiresInDays: 7,
+  expiresAt: "2026-06-13T00:00:00.000Z",
 });
 
 add("org.unit_owner_granted", "Unit owner + message", {
   granterName: "Jordan Lee",
   recipientName: "Sam Chen",
+  orgName: "Acme Corp",
   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", {
+add("org.unit_owner_granted", "Delegate with expiry", {
   granterName: "Jordan Lee",
+  orgName: "Acme Corp",
   unitName: "Platform Engineering",
   roleLabel: "Delegate",
   ctaUrl: `${APP}/org/unit/42`,
+  expiresAt: "2026-06-13T00:00:00.000Z",
 });
 
-add("org.ownership_transfer", "With note", {
+add("org.ownership_transfer", "With note + from", {
   orgName: "Acme Corp",
   acceptUrl: `${APP}/owner-transfer/accept/tok123`,
-  expiresInDays: 14,
+  expiresAt: "2026-06-13T00:00:00.000Z",
   note: "Handing this over as I move to an advisory role.",
+  fromName: "Jordan Lee",
 });
-add("org.ownership_transfer", "No note", {
+add("org.ownership_transfer", "No note (admin)", {
   orgName: "Acme Corp",
   acceptUrl: `${APP}/owner-transfer/accept/tok456`,
-  expiresInDays: 14,
+  expiresAt: "2026-06-13T00:00:00.000Z",
 });
 
 add("org.ownership_transfer_completed", "Default", {

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

@@ -10,12 +10,13 @@ import type { EmailPayloads } from "../types";
 
 import {
   type Block,
-  ctaBox,
   footer,
+  greeting,
   keyValue,
   paragraph,
   signature,
 } from "./blocks";
+import { chatAssistant, chatCta, chatUnit } from "./chat";
 import { COMPANY_NAME } from "./constants";
 
 export type AuthOtpPayload = EmailPayloads["auth.otp"];
@@ -32,9 +33,13 @@ export function renderAuthOtp(
   const { otp, expiresInMinutes, requestIp, userAgent } = payload;
 
   const blocks: Block[] = [
-    paragraph("Copy/paste code in login form:"),
-    ctaBox({ label: otp, variant: "code" }),
-    keyValue("Status", "VALID"),
+    greeting(),
+    paragraph("A login code was requested."),
+    chatUnit(
+      chatAssistant("Copy + paste this code in the login form."),
+      chatCta({ label: otp }),
+    ),
+    keyValue("Status", "Valid"),
     keyValue(
       "Expires in",
       `${expiresInMinutes} ${expiresInMinutes === 1 ? "minute" : "minutes"}`,
@@ -55,10 +60,10 @@ export function renderAuthOtp(
 
   blocks.push(
     footer(
-      `This code was generated to authorize a login to ${COMPANY_NAME}.`,
-      "It expires automatically and cannot be reused.",
+      `This login code was sent via ${COMPANY_NAME}.`,
+      "If this wasn't you, no action is required.",
+      "none",
     ),
-    paragraph("If this wasn't you, no action is required."),
     signature(),
   );
 

package/src/email/render/blocks.ts

@@ -7,8 +7,13 @@
  * UI is the components.** Editing a block restyles every email, HTML and plain
  * text, across the backend (real sends) and the app (Ladle preview).
  *
+ * This module holds the primitives — shells, paragraphs, and the CTA box. The
+ * chat unit builds on them from `./chat`; both are re-exported together from
+ * `./index`, which is the surface templates and consumers import.
+ *
  * INVARIANTS:
- * - Pure functions, no side effects.
+ * - Pure functions, no side effects — except `signature()`, which reads the
+ *   current year (`new Date().getFullYear()`) for the copyright line.
  * - Components escape their own content; templates pass raw text (+ `bold(...)`
  *   for inline emphasis). No template hand-writes markup or raw strings.
  */
@@ -16,11 +21,14 @@
 import { COMPANY_NAME, MONO_FONT_STACK } from "./constants";
 import { escapeHtml } from "./escape-html";
 
-const MONO = `font-family: ${MONO_FONT_STACK};`;
+/** Shared type styling. Exported for `./chat` only — not part of the package
+ * surface (`./index` does not re-export these), so components stay the one
+ * place styling is decided. */
+export const MONO = `font-family: ${MONO_FONT_STACK};`;
 
 /** The single font size for every email element (HTML). Plain text is monospace
  * so it carries no size — this keeps one visual size across both surfaces. */
-const FONT_SIZE = "13px";
+export const FONT_SIZE = "13px";
 
 // =============================================================================
 // Core types
@@ -43,9 +51,17 @@ export interface Inline {
 /** Paragraph content: raw string(s) (auto-escaped for HTML) and/or `bold(...)`. */
 export type InlineContent = string | Inline | Array<string | Inline>;
 
-/** Bold inline emphasis (plain in text). */
+/** Inline emphasis segment. Emphasis is currently visually flat — it renders
+ * plain (no bold) in both surfaces; the seam is kept so all inline emphasis can
+ * be restyled in one place. */
 export function bold(s: string): Inline {
-  return { html: `<b>${escapeHtml(s)}</b>`, text: s };
+  return { html: escapeHtml(s), text: s };
+}
+
+/** Title-case a display value — capitalize the first letter of each word, e.g. a
+ * role like "admin" → "Admin". Leaves already-capitalized letters untouched. */
+export function titleCase(s: string): string {
+  return s.replace(/\b\w/g, (c) => c.toUpperCase());
 }
 
 /** Normalize a segment: a raw string is escaped for HTML, passed through for text. */
@@ -83,7 +99,9 @@ export function htmlShell(blocks: Block[]): string {
 <html lang="en">
 <head><meta charset="UTF-8"></head>
 <body style="${MONO} color: #1a1a1a; margin: 0; padding: 0;">
+<div style="max-width: 520px; margin: 0 auto;">
 ${inner}
+</div>
 </body>
 </html>`;
 }
@@ -120,9 +138,30 @@ export function paragraph(
   };
 }
 
-/** "Hi Name," / "Hi," greeting. */
+/** "Hi Name," greeting; falls back to "Hi there," when the name is unknown. */
 export function greeting(recipientName?: string): Block {
-  return paragraph(recipientName ? `Hi ${recipientName},` : "Hi,");
+  return paragraph(recipientName ? `Hi ${recipientName},` : "Hi there,");
+}
+
+/** Security banner — the "WARNING" wordmark, sits atop security emails. */
+export function security(): Block {
+  return paragraph("🆆🅰🆁🅽🅸🅽🅶");
+}
+
+/**
+ * Format an ISO timestamp as "Jun 13, 2026". Pinned to en-US + UTC so the
+ * output is locale-/timezone-independent and render snapshots stay
+ * deterministic. Returns the raw input unchanged if it is not a parseable date.
+ */
+export function formatExpiry(iso: string): string {
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return iso;
+  return d.toLocaleDateString("en-US", {
+    month: "short",
+    day: "numeric",
+    year: "numeric",
+    timeZone: "UTC",
+  });
 }
 
 /** "Label: **value**" key/value row (value bold in HTML; tight by default). */
@@ -152,12 +191,16 @@ export function footer(
 }
 
 /**
- * Trailing sign-off — the company (or custom `signer`) name.
+ * Trailing sign-off — a leading blank line, the `---` rule, then the company
+ * (or custom `signer`) name. Owns the blank above the rule so every sign-off is
+ * spaced identically; the block before it carries no trailing gap.
  */
 export function signature(signer: string = COMPANY_NAME): Block {
+  const line = `ⓒ ${new Date().getFullYear()} • ${signer}`;
+  const url = "https://companysemantics.ai";
   return {
-    html: `<p style="${MONO} font-size: ${FONT_SIZE}; margin: ${SPACING.none};">${escapeHtml(signer)}</p>`,
-    text: `---\n${signer}`,
+    html: `<p style="${MONO} font-size: ${FONT_SIZE}; margin: ${SPACING.none};"><br><br><span style="color: #bbb;">/* EOM */</span><br>${escapeHtml(line)}<br><a href="${url}" target="_blank" rel="noopener noreferrer" style="color: #0047FF; text-decoration: none;">${escapeHtml(url)}</a></p>`,
+    text: `\n\n/* EOM */\n${line}\n${url}`,
     spacing: "none",
   };
 }
@@ -173,56 +216,19 @@ export const ACCESS_PHRASE: Record<"editor" | "commenter" | "viewer", string> =
     viewer: "can view",
   };
 
-/** Centered continuation dots separator (chat-shared). */
-export function chatDots(): Block {
-  return {
-    html: `<p style="${MONO} font-size: ${FONT_SIZE}; margin: 0 0 16px 0; max-width: 320px; text-align: center;">⋮</p>`,
-    text: "                  ⋮",
-    spacing: "normal",
-  };
-}
-
 // =============================================================================
 // CTA box
 // =============================================================================
 
-/** Options for the `>> LABEL <<` call-to-action box. */
+/** Options for the `>> LABEL <<` call-to-action box. Styling is component-owned
+ * (the only allowable UI is the component) — callers supply only content. */
 export interface CtaBoxOptions {
   /** Text between the chevrons (already display-safe). */
   label: string;
   /** When present, the label links to this URL (and the URL rides under the
    * plain-text box). */
   href?: string;
-  /** Visual kind. `"action"` = link CTA (default); `"code"` = copy/paste code
-   * box (square corners, letter-spaced). */
-  variant?: "action" | "code";
-}
-
-/** Component-owned styling per CTA variant. Templates supply only `label`/`href`/
- * `variant` — the only allowable UI is the component, so all CSS lives here,
- * never at the call site. */
-interface CtaVariantStyle {
-  padding: string;
-  fontSize: string;
-  maxWidth?: string;
-  square: boolean;
-  letterSpacing?: string;
 }
-const CTA_VARIANTS: Record<"action" | "code", CtaVariantStyle> = {
-  action: {
-    padding: "16px 24px",
-    fontSize: FONT_SIZE,
-    maxWidth: "220px",
-    square: false,
-  },
-  code: {
-    padding: "16px 24px",
-    fontSize: FONT_SIZE,
-    maxWidth: "220px",
-    square: true,
-    letterSpacing: "4px",
-  },
-};
 
 /** Padding columns on each side of the `>> LABEL <<` line in the ASCII box. */
 const CTA_BOX_PAD = 3;
@@ -235,26 +241,25 @@ function asciiCtaBox(label: string): string {
   return [border, `|${inner}|`, border].join("\n");
 }
 
-/** The bordered `>> LABEL <<` CTA box (OTP / JOIN / OPEN / VIEW TEAM / …). When
- * `href` is given, HTML links the label and plain text prints the URL below. */
-export function ctaBox(opts: CtaBoxOptions): Block {
-  const { label, href, variant = "action" } = opts;
-  const { padding, fontSize, maxWidth, square, letterSpacing } =
-    CTA_VARIANTS[variant];
-
-  const tableStyle =
-    `border: 2px solid #1a1a1a;` +
-    (square ? ` 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; ${escapeHtml(label)} &lt;&lt;</b>`;
+/** The bordered `>> LABEL <<` button (HTML table + ascii text), with `margin` on
+ * the table. `ctaBox` wraps it as a standalone block; a chat unit embeds it
+ * (hence the export — internal to the render layer, not re-exported by `./index`). */
+export function ctaButton(
+  opts: CtaBoxOptions,
+  margin: string,
+): { html: string; text: string } {
+  const { label, href } = opts;
+
+  const tableStyle = `display: inline-block; border: 1px solid #666; border-radius: 2px; margin: ${margin}; max-width: 220px;`;
+  const tdStyle = `padding: 16px 24px; text-align: center; ${MONO} font-size: ${FONT_SIZE};`;
+
+  // Underline only the label text (not the chevrons/spaces), and only when linked.
+  const labelHtml = href
+    ? `<span style="text-decoration: underline;">${escapeHtml(label)}</span>`
+    : escapeHtml(label);
+  const chevrons = `&gt;&gt; ${labelHtml} &lt;&lt;`;
   const inner = href
-    ? `<a href="${href}" style="color: #0047FF; text-decoration: underline;">${chevrons}</a>`
+    ? `<a href="${href}" style="color: #0047FF; text-decoration: none;">${chevrons}</a>`
     : chevrons;
 
   const html = `<table cellpadding="0" cellspacing="0" border="0" style="${tableStyle}">
@@ -265,116 +270,12 @@ export function ctaBox(opts: CtaBoxOptions): Block {
 
   const text = href ? `${asciiCtaBox(label)}\n\n${href}` : asciiCtaBox(label);
 
-  return { html, text, spacing: "normal" };
-}
-
-// =============================================================================
-// Chat bubbles — one dual-output block per role
-// =============================================================================
-
-/** Greedy word-wrap into lines of at most `width` chars (hard-breaks long words). */
-function wrapText(text: string, width: number): string[] {
-  const lines: string[] = [];
-  let cur = "";
-  for (const word of text.split(/\s+/).filter(Boolean)) {
-    let w = word;
-    while (w.length > width) {
-      if (cur) {
-        lines.push(cur);
-        cur = "";
-      }
-      lines.push(w.slice(0, width));
-      w = w.slice(width);
-    }
-    if (!cur) cur = w;
-    else if (cur.length + 1 + w.length <= width) cur += ` ${w}`;
-    else {
-      lines.push(cur);
-      cur = w;
-    }
-  }
-  if (cur) lines.push(cur);
-  return lines.length ? lines : [""];
+  return { html, text };
 }
 
-/** Chat message truncation budget: at most MAX_MESSAGE_LINES lines of MESSAGE_WIDTH chars. */
-const MAX_MESSAGE_LINES = 3;
-const MESSAGE_WIDTH = 35;
-
-/** Word-wrap `text`, then clamp to `maxLines`, ellipsizing the last line on overflow. */
-function wrapClamped(text: string, width: number, maxLines: number): string[] {
-  const lines = wrapText(text, width);
-  if (lines.length <= maxLines) return lines;
-  const kept = lines.slice(0, maxLines);
-  const last = kept[maxLines - 1];
-  kept[maxLines - 1] =
-    (last.length > width - 3 ? last.slice(0, width - 3).trimEnd() : last) +
-    "...";
-  return kept;
-}
-
-/**
- * The one truncation authority: clamp a raw message to MAX_MESSAGE_LINES ×
- * MESSAGE_WIDTH, ellipsized. Both surfaces of a chat block run content through
- * this, so HTML and plain text truncate at exactly the same point.
- */
-function clampMessage(text: string): string {
-  return wrapClamped(text, MESSAGE_WIDTH, MAX_MESSAGE_LINES).join(" ");
-}
-
-/**
- * Right-aligned user chat message. Truncated by clampMessage. In plain text the
- * face sits beside the last message line. When `from` is given (the sender's
- * name) it renders as an attribution below, right-aligned to the message's right
- * edge.
- */
-export function chatUser(content: string, from?: string): Block {
-  const clamped = clampMessage(content);
-
-  const attributionRow = from
-    ? `
-  <tr>
-    <td style="${MONO} font-size: ${FONT_SIZE}; color: #888; text-align: right; padding-top: 4px;">${escapeHtml(from)}</td>
-    <td></td>
-  </tr>`
-    : "";
-  const html = `<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: ${FONT_SIZE}; background: #f5f5f5;">${escapeHtml(clamped)}</td>
-    <td style="${MONO} font-size: ${FONT_SIZE}; padding-left: 8px; vertical-align: bottom;">(•̀_ರ╮)</td>
-  </tr>${attributionRow}
-</table>`;
-
-  const border = "─".repeat(MESSAGE_WIDTH + 1);
-  const lines = wrapText(clamped, MESSAGE_WIDTH);
-  const body = lines.map((line) => `│${line.padStart(MESSAGE_WIDTH)} │`);
-  // Face beside the last message line (one row up from the bottom border).
-  body[body.length - 1] += "  (•̀_ರ╮)";
-  const box = [`┌${border}┐`, ...body, `└${border}┘`];
-  if (from) box.push(from.padStart(MESSAGE_WIDTH + 3));
-
-  return { html, text: box.join("\n"), spacing: "normal" };
-}
-
-/** Left-aligned assistant chat message with `[c_S]` avatar; in plain text the
- * avatar sits beside the last message line (one row up from the bottom border). */
-export function chatAssistant(content: string): Block {
-  const clamped = clampMessage(content);
-
-  const html = `<table cellpadding="0" cellspacing="0" border="0" style="margin: 16px 0;">
-  <tr>
-    <td style="${MONO} font-size: ${FONT_SIZE}; padding-right: 8px; vertical-align: bottom;">[c_S]</td>
-    <td style="border: 1px solid #1a1a1a; border-radius: 12px 12px 12px 0; padding: 10px 14px; min-width: 280px; ${MONO} font-size: ${FONT_SIZE}; background: #f5f5f5;">${escapeHtml(clamped)}</td>
-  </tr>
-</table>`;
-
-  const lineWidth = 36;
-  const lines = wrapText(clamped, lineWidth);
-  const top = "       ┌──────────────────────────────────────┐";
-  const bot = "       └──────────────────────────────────────┘";
-  const boxLines = lines.map((line) => `       │ ${line.padEnd(lineWidth)} │`);
-  // Avatar beside the last message line (one row up from the bottom border).
-  boxLines[boxLines.length - 1] = `[c_S]  ${boxLines[boxLines.length - 1].slice(7)}`;
-
-  return { html, text: [top, ...boxLines, bot].join("\n"), spacing: "normal" };
+/** The bordered `>> LABEL <<` CTA box (OTP / JOIN / OPEN / VIEW TEAM / …). When
+ * `href` is given, HTML links the label and plain text prints the URL below. */
+export function ctaBox(opts: CtaBoxOptions): Block {
+  const { html, text } = ctaButton(opts, "0 0 20px 0");
+  return { html, text, spacing: "normal" };
 }

package/src/email/render/chat-shared.ts

@@ -6,36 +6,30 @@ import type { EmailPayloads } from "../types";
 
 import {
   type Block,
-  chatAssistant,
-  chatDots,
-  chatUser,
-  ctaBox,
   footer,
+  greeting,
   NOTICE,
   paragraph,
   signature,
 } from "./blocks";
+import { chatAssistant, chatCta, chatDots, chatUnit, chatUser } from "./chat";
 import { COMPANY_NAME } from "./constants";
 
 export type ChatSharedPayload = EmailPayloads["chat.shared"];
 
 export function renderChatShared(payload: ChatSharedPayload): Block[] {
-  const { chatTitle, shareUrl, previewText } = payload;
-
-  const blocks: Block[] = [
-    paragraph("A chat has been shared with you."),
-    chatUser(chatTitle),
-  ];
-
-  if (previewText) blocks.push(chatAssistant(previewText));
-
-  blocks.push(
-    chatDots(),
-    ctaBox({ label: "SEE MORE", href: shareUrl }),
-    footer(`This share was sent via ${COMPANY_NAME}.`),
-    paragraph(NOTICE, "tight"),
+  const { chatTitle, shareUrl, previewText, sharedByName } = payload;
+
+  return [
+    greeting(),
+    paragraph("A chat was shared with you."),
+    chatUnit(
+      chatUser(chatTitle, sharedByName),
+      ...(previewText ? [chatAssistant(previewText)] : []),
+      chatDots(),
+      chatCta({ label: "SEE MORE", href: shareUrl }),
+    ),
+    footer(`This share was sent via ${COMPANY_NAME}.`, NOTICE, "none"),
     signature(),
-  );
-
-  return blocks;
+  ];
 }