@company-semantics/contracts 27.13.1 → 28.0.0

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

@@ -1,39 +1,26 @@
 /**
  * Central email dispatcher. Given a kind + payload it returns
  * `{ subject, text, html? }`, pulling the subject from the registry (single
- * source of truth). This is the one entry point both the backend (real sends)
- * and the app (Ladle preview) call.
+ * source of truth) and deriving both surfaces from ONE composed block list
+ * (`htmlShell` + `textShell`). This is the one entry point both the backend
+ * (real sends) and the app (Ladle preview) call.
  */
 
 import { EMAIL_KINDS } from "../registry";
 import type { EmailKind, EmailPayloads } from "../types";
 
-import { renderAuthOtpBody, renderAuthOtpHtml } from "./auth-otp";
-import {
-  renderAccessApprovedBody,
-  renderAccessApprovedHtml,
-} from "./company-md-access-approved";
-import {
-  renderAccessDeniedBody,
-  renderAccessDeniedHtml,
-} from "./company-md-access-denied";
-import {
-  renderAccessRequestedBody,
-  renderAccessRequestedHtml,
-} from "./company-md-access-requested";
-import { renderChatSharedBody, renderChatSharedHtml } from "./chat-shared";
-import { renderOrgInviteBody, renderOrgInviteHtml } from "./org-invite";
-import { renderOwnershipTransferBody } from "./ownership-transfer";
-import { renderOwnershipTransferCompletedBody } from "./ownership-transfer-completed";
-import { renderSecurityAlertBody } from "./security-alert";
-import {
-  renderShareGrantedBody,
-  renderShareGrantedHtml,
-} from "./share-granted";
-import {
-  renderUnitOwnerGrantedBody,
-  renderUnitOwnerGrantedHtml,
-} from "./unit-owner-granted";
+import { renderAuthOtp } from "./auth-otp";
+import { type Block, htmlShell, textShell } from "./blocks";
+import { renderAccessApproved } from "./company-md-access-approved";
+import { renderAccessDenied } from "./company-md-access-denied";
+import { renderAccessRequested } from "./company-md-access-requested";
+import { renderChatShared } from "./chat-shared";
+import { renderOrgInvite } from "./org-invite";
+import { renderOwnershipTransfer } from "./ownership-transfer";
+import { renderOwnershipTransferCompleted } from "./ownership-transfer-completed";
+import { renderSecurityAlert } from "./security-alert";
+import { renderShareGranted } from "./share-granted";
+import { renderUnitOwnerGranted } from "./unit-owner-granted";
 
 /** Rendered email output. */
 export interface RenderedEmail {
@@ -68,16 +55,37 @@ export const IMPLEMENTED_EMAIL_KINDS = [
 
 export type ImplementedEmailKind = (typeof IMPLEMENTED_EMAIL_KINDS)[number];
 
+/**
+ * Kinds delivered as plain text only. The unified block model renders HTML for
+ * every template, but these keep their historical text-only surface — the
+ * dispatcher omits `html` for them. (Enabling HTML later is deleting the entry.)
+ */
+const TEXT_ONLY_KINDS = new Set<EmailKind>([
+  "security.alert",
+  "org.ownership_transfer",
+  "org.ownership_transfer_completed",
+]);
+
 /** Payload type for a kind (or `never` for kinds without a payload). */
 type PayloadFor<K extends EmailKind> = K extends keyof EmailPayloads
   ? EmailPayloads[K]
   : never;
 
+function toEmail(
+  subject: string,
+  kind: EmailKind,
+  blocks: Block[],
+): RenderedEmail {
+  const email: RenderedEmail = { subject, text: textShell(blocks) };
+  if (!TEXT_ONLY_KINDS.has(kind)) email.html = htmlShell(blocks);
+  return email;
+}
+
 /**
- * Render an email by kind. Subject comes from `EMAIL_KINDS`; `html` is present
- * only when the template emits an HTML variant. Accepts the full `EmailKind`
- * union so callers with a generic kind (e.g. the backend `EmailService`) type
- * cleanly; unimplemented kinds throw at runtime.
+ * Render an email by kind. Subject comes from `EMAIL_KINDS`; both surfaces
+ * derive from one composed block list. Accepts the full `EmailKind` union so
+ * callers with a generic kind (e.g. the backend `EmailService`) type cleanly;
+ * unimplemented kinds throw at runtime.
  *
  * @throws if the kind has no implementation.
  */
@@ -89,82 +97,84 @@ export function renderEmail<K extends EmailKind>(
   const subject = EMAIL_KINDS[kind].subject;
 
   switch (kind) {
-    case "auth.otp": {
-      const p = payload as EmailPayloads["auth.otp"];
-      return {
+    case "auth.otp":
+      return toEmail(
         subject,
-        text: renderAuthOtpBody(p, options),
-        html: renderAuthOtpHtml(p),
-      };
-    }
-    case "org.invite": {
-      const p = payload as EmailPayloads["org.invite"];
-      return {
+        kind,
+        renderAuthOtp(payload as EmailPayloads["auth.otp"], options),
+      );
+    case "org.invite":
+      return toEmail(
         subject,
-        text: renderOrgInviteBody(p),
-        html: renderOrgInviteHtml(p),
-      };
-    }
-    case "org.unit_owner_granted": {
-      const p = payload as EmailPayloads["org.unit_owner_granted"];
-      return {
+        kind,
+        renderOrgInvite(payload as EmailPayloads["org.invite"]),
+      );
+    case "org.unit_owner_granted":
+      return toEmail(
         subject,
-        text: renderUnitOwnerGrantedBody(p),
-        html: renderUnitOwnerGrantedHtml(p),
-      };
-    }
-    case "org.ownership_transfer": {
-      const p = payload as EmailPayloads["org.ownership_transfer"];
-      return { subject, text: renderOwnershipTransferBody(p) };
-    }
-    case "org.ownership_transfer_completed": {
-      const p = payload as EmailPayloads["org.ownership_transfer_completed"];
-      return { subject, text: renderOwnershipTransferCompletedBody(p) };
-    }
-    case "security.alert": {
-      const p = payload as EmailPayloads["security.alert"];
-      return { subject, text: renderSecurityAlertBody(p) };
-    }
-    case "chat.shared": {
-      const p = payload as EmailPayloads["chat.shared"];
-      return {
+        kind,
+        renderUnitOwnerGranted(
+          payload as EmailPayloads["org.unit_owner_granted"],
+        ),
+      );
+    case "org.ownership_transfer":
+      return toEmail(
         subject,
-        text: renderChatSharedBody(p),
-        html: renderChatSharedHtml(p),
-      };
-    }
-    case "share.granted": {
-      const p = payload as EmailPayloads["share.granted"];
-      return {
+        kind,
+        renderOwnershipTransfer(
+          payload as EmailPayloads["org.ownership_transfer"],
+        ),
+      );
+    case "org.ownership_transfer_completed":
+      return toEmail(
         subject,
-        text: renderShareGrantedBody(p),
-        html: renderShareGrantedHtml(p),
-      };
-    }
-    case "companyMd.access_requested": {
-      const p = payload as EmailPayloads["companyMd.access_requested"];
-      return {
+        kind,
+        renderOwnershipTransferCompleted(
+          payload as EmailPayloads["org.ownership_transfer_completed"],
+        ),
+      );
+    case "security.alert":
+      return toEmail(
         subject,
-        text: renderAccessRequestedBody(p),
-        html: renderAccessRequestedHtml(p),
-      };
-    }
-    case "companyMd.access_request_approved": {
-      const p = payload as EmailPayloads["companyMd.access_request_approved"];
-      return {
+        kind,
+        renderSecurityAlert(payload as EmailPayloads["security.alert"]),
+      );
+    case "chat.shared":
+      return toEmail(
         subject,
-        text: renderAccessApprovedBody(p),
-        html: renderAccessApprovedHtml(p),
-      };
-    }
-    case "companyMd.access_request_denied": {
-      const p = payload as EmailPayloads["companyMd.access_request_denied"];
-      return {
+        kind,
+        renderChatShared(payload as EmailPayloads["chat.shared"]),
+      );
+    case "share.granted":
+      return toEmail(
         subject,
-        text: renderAccessDeniedBody(p),
-        html: renderAccessDeniedHtml(p),
-      };
-    }
+        kind,
+        renderShareGranted(payload as EmailPayloads["share.granted"]),
+      );
+    case "companyMd.access_requested":
+      return toEmail(
+        subject,
+        kind,
+        renderAccessRequested(
+          payload as EmailPayloads["companyMd.access_requested"],
+        ),
+      );
+    case "companyMd.access_request_approved":
+      return toEmail(
+        subject,
+        kind,
+        renderAccessApproved(
+          payload as EmailPayloads["companyMd.access_request_approved"],
+        ),
+      );
+    case "companyMd.access_request_denied":
+      return toEmail(
+        subject,
+        kind,
+        renderAccessDenied(
+          payload as EmailPayloads["companyMd.access_request_denied"],
+        ),
+      );
     default: {
       // Reachable for registered-but-unimplemented kinds (e.g. auth.magic_link).
       const unimplemented: string = kind;

package/src/email/render/security-alert.ts

@@ -1,13 +1,10 @@
 /**
- * Security alert email (plain text only).
- *
- * Uses a single shared footer via `baseTextLayout` with a "Security" signer —
- * the previous copy hand-rolled a second footer, printing two.
+ * Security alert email (plain text only). Signs off with a "Security" signer.
  */
 
 import type { EmailPayloads } from "../types";
 
-import { baseTextLayout } from "./base-text";
+import { type Block, keyValue, paragraph, signature } from "./blocks";
 import { COMPANY_NAME } from "./constants";
 
 export type SecurityAlertPayload = EmailPayloads["security.alert"];
@@ -18,34 +15,35 @@ export const SECURITY_ALERT_TYPES = [
   "unusual_login_location",
 ] as const;
 
-export function renderSecurityAlertBody(payload: SecurityAlertPayload): string {
+export function renderSecurityAlert(payload: SecurityAlertPayload): Block[] {
   const { alertType, details, timestamp } = payload;
 
-  const sections: string[] = [];
+  const blocks: Block[] = [];
 
   switch (alertType) {
     case "excessive_otp_requests":
-      sections.push(
-        "We detected an unusual number of login code requests for your account.",
+      blocks.push(
+        paragraph(
+          "We detected an unusual number of login code requests for your account.",
+        ),
+        keyValue("Details", details, "normal"),
+        paragraph("If this was you, no action is needed.", "tight"),
+        paragraph(
+          "If you didn't request these codes, someone may be trying to access your account.",
+          "tight",
+        ),
+        paragraph("We recommend reviewing your account security."),
       );
-      sections.push("");
-      sections.push(`Details: ${details}`);
-      sections.push("");
-      sections.push("If this was you, no action is needed.");
-      sections.push(
-        "If you didn't request these codes, someone may be trying to access your account.",
-      );
-      sections.push("We recommend reviewing your account security.");
       break;
 
     case "unusual_login_location":
-      sections.push("We detected a login attempt from an unusual location.");
-      sections.push("");
-      sections.push(`Details: ${details}`);
-      sections.push("");
-      sections.push("If this was you, no action is needed.");
-      sections.push(
-        "If you didn't attempt to log in, please secure your account immediately.",
+      blocks.push(
+        paragraph("We detected a login attempt from an unusual location."),
+        keyValue("Details", details, "normal"),
+        paragraph("If this was you, no action is needed.", "tight"),
+        paragraph(
+          "If you didn't attempt to log in, please secure your account immediately.",
+        ),
       );
       break;
 
@@ -55,8 +53,10 @@ export function renderSecurityAlertBody(payload: SecurityAlertPayload): string {
     }
   }
 
-  sections.push("");
-  sections.push(`Time: ${new Date(timestamp).toUTCString()}`);
+  blocks.push(
+    keyValue("Time", new Date(timestamp).toUTCString(), "normal"),
+    signature(`${COMPANY_NAME} Security`),
+  );
 
-  return baseTextLayout(sections.join("\n"), `${COMPANY_NAME} Security`);
+  return blocks;
 }

package/src/email/render/share-granted.ts

@@ -1,62 +1,27 @@
 /**
- * Share-granted email (an entity was shared with the recipient). Text + HTML.
+ * Share-granted email (an entity was shared with the recipient).
  */
 
 import type { EmailPayloads } from "../types";
 
-import { baseTextLayout } from "./base-text";
 import {
   ACCESS_PHRASE,
-  asciiCtaBox,
-  bodyParagraph,
+  type Block,
+  bold,
+  chatUser,
   ctaBox,
   footer,
   greeting,
-  htmlShell,
+  type Inline,
   NOTICE,
-  quoteBlock,
-  signatureLine,
-  textQuote,
+  paragraph,
+  signature,
 } from "./blocks";
 import { COMPANY_NAME } from "./constants";
-import { escapeHtml } from "./escape-html";
 
 export type ShareGrantedPayload = EmailPayloads["share.granted"];
 
-/** `the document "Roadmap"` — or `a document` when there is no title. */
-function describeEntity(payload: ShareGrantedPayload): string {
-  return payload.entityTitle
-    ? `the ${payload.entityLabel} "${payload.entityTitle}"`
-    : `a ${payload.entityLabel}`;
-}
-
-export function renderShareGrantedBody(payload: ShareGrantedPayload): string {
-  const { granterName, recipientName, accessLevel, ctaUrl, message } = payload;
-
-  const sections: string[] = [];
-  sections.push(recipientName ? `Hi ${recipientName},` : "Hi,");
-  sections.push("");
-  sections.push(
-    `${granterName} shared ${describeEntity(payload)} with you — you ${ACCESS_PHRASE[accessLevel]}.`,
-  );
-
-  if (message) {
-    sections.push("");
-    sections.push(textQuote(`Message from ${granterName}`, message));
-  }
-
-  sections.push("");
-  sections.push(asciiCtaBox("OPEN"));
-  sections.push("");
-  sections.push(ctaUrl);
-  sections.push("");
-  sections.push(`This notification was sent via ${COMPANY_NAME}.`);
-  sections.push(NOTICE);
-
-  return baseTextLayout(sections.join("\n"));
-}
-
-export function renderShareGrantedHtml(payload: ShareGrantedPayload): string {
+export function renderShareGranted(payload: ShareGrantedPayload): Block[] {
   const {
     granterName,
     recipientName,
@@ -67,21 +32,23 @@ export function renderShareGrantedHtml(payload: ShareGrantedPayload): string {
     message,
   } = payload;
 
-  const entityHtml = entityTitle
-    ? `the ${escapeHtml(entityLabel)} <b>"${escapeHtml(entityTitle)}"</b>`
-    : `a ${escapeHtml(entityLabel)}`;
+  const entity: Array<string | Inline> = entityTitle
+    ? [`the ${entityLabel} `, bold(`"${entityTitle}"`)]
+    : [`a ${entityLabel}`];
 
-  return htmlShell([
+  const blocks: Block[] = [
     greeting(recipientName),
-    bodyParagraph(
-      `<b>${escapeHtml(granterName)}</b> shared ${entityHtml} with you &mdash; you ${ACCESS_PHRASE[accessLevel]}.`,
-    ),
-    message
-      ? quoteBlock(
-          `Message from ${escapeHtml(granterName)}:`,
-          escapeHtml(message),
-        )
-      : "",
+    paragraph([
+      bold(granterName),
+      " shared ",
+      ...entity,
+      ` with you — you ${ACCESS_PHRASE[accessLevel]}.`,
+    ]),
+  ];
+
+  if (message) blocks.push(chatUser(message, `Message from ${granterName}`));
+
+  blocks.push(
     ctaBox({
       label: "OPEN",
       href: ctaUrl,
@@ -90,6 +57,8 @@ export function renderShareGrantedHtml(payload: ShareGrantedPayload): string {
       maxWidth: "220px",
     }),
     footer(`This notification was sent via ${COMPANY_NAME}.`, NOTICE),
-    signatureLine(),
-  ]);
+    signature(),
+  );
+
+  return blocks;
 }

package/src/email/render/unit-owner-granted.ts

@@ -1,71 +1,45 @@
 /**
- * Unit-owner-granted email (added to a team's unit ownership). Text + HTML.
+ * Unit-owner-granted email (added to a team's unit ownership).
  */
 
 import type { EmailPayloads } from "../types";
 
-import { baseTextLayout } from "./base-text";
 import {
-  asciiCtaBox,
-  bodyParagraph,
+  type Block,
+  bold,
+  chatUser,
   ctaBox,
   footer,
   greeting,
-  htmlShell,
   NOTICE,
-  quoteBlock,
-  signatureLine,
-  textQuote,
+  paragraph,
+  signature,
 } from "./blocks";
 import { COMPANY_NAME } from "./constants";
-import { escapeHtml } from "./escape-html";
 
 export type UnitOwnerGrantedPayload = EmailPayloads["org.unit_owner_granted"];
 
-export function renderUnitOwnerGrantedBody(
+export function renderUnitOwnerGranted(
   payload: UnitOwnerGrantedPayload,
-): string {
+): Block[] {
   const { granterName, recipientName, unitName, roleLabel, ctaUrl, message } =
     payload;
 
-  const sections: string[] = [];
-  sections.push(recipientName ? `Hi ${recipientName},` : "Hi,");
-  sections.push("");
-  sections.push(`${granterName} added you as a ${roleLabel} of "${unitName}".`);
-
-  if (message) {
-    sections.push("");
-    sections.push(textQuote(`Message from ${granterName}`, message));
-  }
-
-  sections.push("");
-  sections.push(asciiCtaBox("VIEW TEAM"));
-  sections.push("");
-  sections.push(ctaUrl);
-  sections.push("");
-  sections.push(`This notification was sent via ${COMPANY_NAME}.`);
-  sections.push(NOTICE);
-
-  return baseTextLayout(sections.join("\n"));
-}
-
-export function renderUnitOwnerGrantedHtml(
-  payload: UnitOwnerGrantedPayload,
-): string {
-  const { granterName, recipientName, unitName, roleLabel, ctaUrl, message } =
-    payload;
-
-  return htmlShell([
+  const blocks: Block[] = [
     greeting(recipientName),
-    bodyParagraph(
-      `<b>${escapeHtml(granterName)}</b> added you as a <b>${escapeHtml(roleLabel)}</b> of <b>${escapeHtml(unitName)}</b>.`,
-    ),
-    message
-      ? quoteBlock(
-          `Message from ${escapeHtml(granterName)}:`,
-          escapeHtml(message),
-        )
-      : "",
+    paragraph([
+      bold(granterName),
+      " added you as a ",
+      bold(roleLabel),
+      " of ",
+      bold(unitName),
+      ".",
+    ]),
+  ];
+
+  if (message) blocks.push(chatUser(message, `Message from ${granterName}`));
+
+  blocks.push(
     ctaBox({
       label: "VIEW TEAM",
       href: ctaUrl,
@@ -74,6 +48,8 @@ export function renderUnitOwnerGrantedHtml(
       maxWidth: "220px",
     }),
     footer(`This notification was sent via ${COMPANY_NAME}.`, NOTICE),
-    signatureLine(),
-  ]);
+    signature(),
+  );
+
+  return blocks;
 }

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

@@ -1,26 +0,0 @@
-/**
- * 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";
-}