@company-semantics/contracts 27.13.1 → 28.0.0

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

@@ -1,79 +1,35 @@
 /**
- * Chat-shared email (someone shared a chat). Plain text + HTML.
+ * Chat-shared email (someone shared a chat).
  */
 
 import type { EmailPayloads } from "../types";
 
-import { baseTextLayout } from "./base-text";
 import {
-  asciiCtaBox,
-  bodyParagraph,
-  chatAssistantBoxText,
-  chatAssistantBubble,
+  type Block,
+  chatAssistant,
   chatDots,
-  chatDotsText,
-  chatUserBoxText,
-  chatUserBubble,
+  chatUser,
   ctaBox,
   footer,
-  htmlShell,
-  monoParagraph,
   NOTICE,
-  signatureLine,
+  paragraph,
+  signature,
 } from "./blocks";
-import {
-  COMPANY_NAME,
-  PREVIEW_TRUNCATE_LENGTH,
-  TITLE_TRUNCATE_LENGTH,
-} from "./constants";
-import { escapeHtml } from "./escape-html";
+import { COMPANY_NAME } from "./constants";
 
 export type ChatSharedPayload = EmailPayloads["chat.shared"];
 
-function truncate(text: string, max: number): string {
-  return text.length > max ? text.slice(0, max - 3) + "..." : text;
-}
-
-export function renderChatSharedBody(payload: ChatSharedPayload): string {
+export function renderChatShared(payload: ChatSharedPayload): Block[] {
   const { chatTitle, shareUrl, previewText } = payload;
 
-  const sections: string[] = [];
-  sections.push("A chat has been shared with you.");
-  sections.push("");
-  sections.push(chatUserBoxText(chatTitle));
-
-  if (previewText) {
-    sections.push("");
-    sections.push(chatAssistantBoxText(previewText));
-  }
-
-  sections.push("");
-  sections.push(chatDotsText());
-  sections.push("");
-  sections.push(asciiCtaBox("SEE MORE"));
-  sections.push("");
-  sections.push(shareUrl);
-  sections.push("");
-  sections.push(`This share was sent via ${COMPANY_NAME}.`);
-  sections.push("");
-  sections.push(NOTICE);
+  const blocks: Block[] = [
+    paragraph("A chat has been shared with you."),
+    chatUser(chatTitle),
+  ];
 
-  return baseTextLayout(sections.join("\n"));
-}
-
-export function renderChatSharedHtml(payload: ChatSharedPayload): string {
-  const { chatTitle, shareUrl, previewText } = payload;
+  if (previewText) blocks.push(chatAssistant(previewText));
 
-  const title = escapeHtml(truncate(chatTitle, TITLE_TRUNCATE_LENGTH));
-  const previewHtml = previewText
-    ? chatAssistantBubble(
-        escapeHtml(truncate(previewText, PREVIEW_TRUNCATE_LENGTH)),
-      )
-    : "";
-
-  return htmlShell([
-    bodyParagraph("A chat has been shared with you."),
-    chatUserBubble(title) + previewHtml,
+  blocks.push(
     chatDots(),
     ctaBox({
       label: "SEE MORE",
@@ -83,7 +39,9 @@ export function renderChatSharedHtml(payload: ChatSharedPayload): string {
       maxWidth: "200px",
     }),
     footer(`This share was sent via ${COMPANY_NAME}.`),
-    monoParagraph(NOTICE, "tight"),
-    signatureLine(),
-  ]);
+    paragraph(NOTICE, "tight"),
+    signature(),
+  );
+
+  return blocks;
 }

package/src/email/render/company-md-access-approved.ts

@@ -1,56 +1,35 @@
 /**
- * Company.md access-approved email (sent to the requester). Text + HTML.
+ * Company.md access-approved email (sent to the requester).
  */
 
 import type { EmailPayloads } from "../types";
 
-import { baseTextLayout } from "./base-text";
 import {
   ACCESS_PHRASE,
-  asciiCtaBox,
-  bodyParagraph,
+  type Block,
+  bold,
   ctaBox,
   footer,
   greeting,
-  htmlShell,
+  paragraph,
+  signature,
 } from "./blocks";
 import { COMPANY_NAME } from "./constants";
-import { escapeHtml } from "./escape-html";
 
 export type AccessApprovedPayload =
   EmailPayloads["companyMd.access_request_approved"];
 
-export function renderAccessApprovedBody(
-  payload: AccessApprovedPayload,
-): string {
+export function renderAccessApproved(payload: AccessApprovedPayload): Block[] {
   const { approverName, docTitle, accessLevel, docUrl } = payload;
 
-  const sections: string[] = [];
-  sections.push("Hi,");
-  sections.push("");
-  sections.push(
-    `${approverName} approved your request to access "${docTitle}" — you ${ACCESS_PHRASE[accessLevel]}.`,
-  );
-  sections.push("");
-  sections.push(asciiCtaBox("OPEN"));
-  sections.push("");
-  sections.push(docUrl);
-  sections.push("");
-  sections.push(`This notification was sent via ${COMPANY_NAME}.`);
-
-  return baseTextLayout(sections.join("\n"));
-}
-
-export function renderAccessApprovedHtml(
-  payload: AccessApprovedPayload,
-): string {
-  const { approverName, docTitle, accessLevel, docUrl } = payload;
-
-  return htmlShell([
+  return [
     greeting(),
-    bodyParagraph(
-      `<b>${escapeHtml(approverName)}</b> approved your request to access <b>"${escapeHtml(docTitle)}"</b> &mdash; you ${ACCESS_PHRASE[accessLevel]}.`,
-    ),
+    paragraph([
+      bold(approverName),
+      " approved your request to access ",
+      bold(`"${docTitle}"`),
+      ` — you ${ACCESS_PHRASE[accessLevel]}.`,
+    ]),
     ctaBox({
       label: "OPEN",
       href: docUrl,
@@ -58,10 +37,7 @@ export function renderAccessApprovedHtml(
       fontSize: "16px",
       maxWidth: "220px",
     }),
-    footer(
-      `This notification was sent via ${COMPANY_NAME}.`,
-      undefined,
-      "none",
-    ),
-  ]);
+    footer(`This notification was sent via ${COMPANY_NAME}.`),
+    signature(),
+  ];
 }

package/src/email/render/company-md-access-denied.ts

@@ -1,63 +1,42 @@
 /**
- * Company.md access-denied email (sent to the requester). No CTA. Text + HTML.
+ * Company.md access-denied email (sent to the requester). No CTA.
  */
 
 import type { EmailPayloads } from "../types";
 
-import { baseTextLayout } from "./base-text";
 import {
-  bodyParagraph,
+  type Block,
+  bold,
+  chatUser,
   footer,
   greeting,
-  htmlShell,
-  quoteBlock,
-  textQuote,
+  paragraph,
+  signature,
 } from "./blocks";
 import { COMPANY_NAME } from "./constants";
-import { escapeHtml } from "./escape-html";
 
 export type AccessDeniedPayload =
   EmailPayloads["companyMd.access_request_denied"];
 
-export function renderAccessDeniedBody(payload: AccessDeniedPayload): string {
+export function renderAccessDenied(payload: AccessDeniedPayload): Block[] {
   const { approverName, docTitle, reason } = payload;
 
-  const sections: string[] = [];
-  sections.push("Hi,");
-  sections.push("");
-  sections.push(
-    `${approverName} declined your request to access "${docTitle}".`,
+  const blocks: Block[] = [
+    greeting(),
+    paragraph([
+      bold(approverName),
+      " declined your request to access ",
+      bold(`"${docTitle}"`),
+      ".",
+    ]),
+  ];
+
+  if (reason) blocks.push(chatUser(reason, `Reason from ${approverName}`));
+
+  blocks.push(
+    footer(`This notification was sent via ${COMPANY_NAME}.`),
+    signature(),
   );
 
-  if (reason) {
-    sections.push("");
-    sections.push(textQuote(`Reason from ${approverName}`, reason));
-  }
-
-  sections.push("");
-  sections.push(`This notification was sent via ${COMPANY_NAME}.`);
-
-  return baseTextLayout(sections.join("\n"));
-}
-
-export function renderAccessDeniedHtml(payload: AccessDeniedPayload): string {
-  const { approverName, docTitle, reason } = payload;
-
-  return htmlShell([
-    greeting(),
-    bodyParagraph(
-      `<b>${escapeHtml(approverName)}</b> declined your request to access <b>"${escapeHtml(docTitle)}"</b>.`,
-    ),
-    reason
-      ? quoteBlock(
-          `Reason from ${escapeHtml(approverName)}:`,
-          escapeHtml(reason),
-        )
-      : "",
-    footer(
-      `This notification was sent via ${COMPANY_NAME}.`,
-      undefined,
-      "none",
-    ),
-  ]);
+  return blocks;
 }

package/src/email/render/company-md-access-requested.ts

@@ -1,71 +1,44 @@
 /**
- * Company.md access-requested email (sent to the doc owner). Text + HTML.
+ * Company.md access-requested email (sent to the doc owner).
  */
 
 import type { EmailPayloads } from "../types";
 
-import { baseTextLayout } from "./base-text";
 import {
-  asciiCtaBox,
-  bodyParagraph,
+  type Block,
+  bold,
+  chatUser,
   ctaBox,
   footer,
   greeting,
-  htmlShell,
-  quoteBlock,
-  signatureLine,
-  textQuote,
+  paragraph,
+  signature,
 } from "./blocks";
 import { COMPANY_NAME } from "./constants";
-import { escapeHtml } from "./escape-html";
 
 export type AccessRequestedPayload =
   EmailPayloads["companyMd.access_requested"];
 
 const OWNER_NOTE = "You are receiving this because you own this document.";
 
-export function renderAccessRequestedBody(
+export function renderAccessRequested(
   payload: AccessRequestedPayload,
-): string {
+): Block[] {
   const { requesterName, docTitle, message, reviewUrl } = payload;
 
-  const sections: string[] = [];
-  sections.push("Hi,");
-  sections.push("");
-  sections.push(`${requesterName} is requesting access to "${docTitle}".`);
-
-  if (message) {
-    sections.push("");
-    sections.push(textQuote(`Message from ${requesterName}`, message));
-  }
+  const blocks: Block[] = [
+    greeting(),
+    paragraph([
+      bold(requesterName),
+      " is requesting access to ",
+      bold(`"${docTitle}"`),
+      ".",
+    ]),
+  ];
 
-  sections.push("");
-  sections.push(asciiCtaBox("REVIEW"));
-  sections.push("");
-  sections.push(reviewUrl);
-  sections.push("");
-  sections.push(`This notification was sent via ${COMPANY_NAME}.`);
-  sections.push(OWNER_NOTE);
+  if (message) blocks.push(chatUser(message, `Message from ${requesterName}`));
 
-  return baseTextLayout(sections.join("\n"));
-}
-
-export function renderAccessRequestedHtml(
-  payload: AccessRequestedPayload,
-): string {
-  const { requesterName, docTitle, message, reviewUrl } = payload;
-
-  return htmlShell([
-    greeting(),
-    bodyParagraph(
-      `<b>${escapeHtml(requesterName)}</b> is requesting access to <b>"${escapeHtml(docTitle)}"</b>.`,
-    ),
-    message
-      ? quoteBlock(
-          `Message from ${escapeHtml(requesterName)}:`,
-          escapeHtml(message),
-        )
-      : "",
+  blocks.push(
     ctaBox({
       label: "REVIEW",
       href: reviewUrl,
@@ -74,6 +47,8 @@ export function renderAccessRequestedHtml(
       maxWidth: "220px",
     }),
     footer(`This notification was sent via ${COMPANY_NAME}.`, OWNER_NOTE),
-    signatureLine(),
-  ]);
+    signature(),
+  );
+
+  return blocks;
 }

package/src/email/render/constants.ts

@@ -16,9 +16,3 @@ export const SUPPORT_EMAIL = "support@companysemantics.ai";
 /** Monospace font stack for HTML emails. */
 export const MONO_FONT_STACK =
   "'SF Mono', SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace";
-
-/** Max chat-title length before truncation (chat-shared). */
-export const TITLE_TRUNCATE_LENGTH = 30;
-
-/** Max preview-text length before truncation (chat-shared). */
-export const PREVIEW_TRUNCATE_LENGTH = 70;

package/src/email/render/index.ts

@@ -6,40 +6,30 @@
  */
 
 // Constants
-export {
-  COMPANY_NAME,
-  SUPPORT_EMAIL,
-  MONO_FONT_STACK,
-  TITLE_TRUNCATE_LENGTH,
-  PREVIEW_TRUNCATE_LENGTH,
-} from "./constants";
+export { COMPANY_NAME, SUPPORT_EMAIL, MONO_FONT_STACK } from "./constants";
 
 // Primitives
 export { escapeHtml } from "./escape-html";
-export { baseTextLayout } from "./base-text";
 
-// Shared building blocks
+// Dual-output building blocks (each returns a `Block` = { html, text })
 export {
   htmlShell,
-  bodyParagraph,
+  textShell,
+  paragraph,
   greeting,
-  monoParagraph,
-  metaRow,
+  keyValue,
   footer,
-  signatureLine,
+  signature,
   NOTICE,
   ACCESS_PHRASE,
   chatDots,
   ctaBox,
-  quoteBlock,
-  chatUserBubble,
-  chatAssistantBubble,
-  asciiCtaBox,
-  asciiCodeBox,
-  textQuote,
-  chatDotsText,
-  chatUserBoxText,
-  chatAssistantBoxText,
+  chatUser,
+  chatAssistant,
+  bold,
+  type Block,
+  type Inline,
+  type InlineContent,
   type Spacing,
   type CtaBoxOptions,
 } from "./blocks";
@@ -53,39 +43,6 @@ export {
   type RenderEmailOptions,
 } from "./render-email";
 
-// Templates
-export {
-  renderAuthOtpBody,
-  renderAuthOtpHtml,
-  type AuthOtpPayload,
-  type RenderOptions,
-} from "./auth-otp";
-export { renderOrgInviteBody, renderOrgInviteHtml } from "./org-invite";
-export { renderChatSharedBody, renderChatSharedHtml } from "./chat-shared";
-export {
-  renderSecurityAlertBody,
-  SECURITY_ALERT_TYPES,
-  type SecurityAlertType,
-} from "./security-alert";
-export {
-  renderUnitOwnerGrantedBody,
-  renderUnitOwnerGrantedHtml,
-} from "./unit-owner-granted";
-export {
-  renderShareGrantedBody,
-  renderShareGrantedHtml,
-} from "./share-granted";
-export { renderOwnershipTransferBody } from "./ownership-transfer";
-export { renderOwnershipTransferCompletedBody } from "./ownership-transfer-completed";
-export {
-  renderAccessRequestedBody,
-  renderAccessRequestedHtml,
-} from "./company-md-access-requested";
-export {
-  renderAccessApprovedBody,
-  renderAccessApprovedHtml,
-} from "./company-md-access-approved";
-export {
-  renderAccessDeniedBody,
-  renderAccessDeniedHtml,
-} from "./company-md-access-denied";
+// Template payload types + alert vocabulary
+export type { AuthOtpPayload, RenderOptions } from "./auth-otp";
+export { SECURITY_ALERT_TYPES, type SecurityAlertType } from "./security-alert";

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

@@ -1,61 +1,38 @@
 /**
- * Org invite email (join a workspace). Plain text + HTML.
+ * Org invite email (join a workspace).
  */
 
 import type { EmailPayloads } from "../types";
 
-import { baseTextLayout } from "./base-text";
 import {
-  asciiCtaBox,
-  bodyParagraph,
+  type Block,
   ctaBox,
   footer,
-  htmlShell,
-  metaRow,
+  keyValue,
   NOTICE,
-  signatureLine,
+  paragraph,
+  signature,
 } from "./blocks";
 import { COMPANY_NAME } from "./constants";
-import { escapeHtml } from "./escape-html";
 
 export type OrgInvitePayload = EmailPayloads["org.invite"];
 
-export function renderOrgInviteBody(payload: OrgInvitePayload): string {
+export function renderOrgInvite(payload: OrgInvitePayload): Block[] {
   const { inviterName, orgName, role, acceptUrl, expiresInDays } = payload;
 
-  const sections: string[] = [];
-  sections.push("Workspace invitation.");
-  sections.push(asciiCtaBox("JOIN"));
-  sections.push("");
-  sections.push(`From: ${inviterName}`);
-  sections.push(`Workspace: ${orgName}`);
-  sections.push(`Role: ${role}`);
-  sections.push(`Expires in: ${expiresInDays} days`);
-  sections.push("");
-  sections.push(acceptUrl);
-  sections.push("");
-  sections.push(`This invitation was sent via ${COMPANY_NAME}.`);
-  sections.push(NOTICE);
-
-  return baseTextLayout(sections.join("\n"));
-}
-
-export function renderOrgInviteHtml(payload: OrgInvitePayload): string {
-  const { inviterName, orgName, role, acceptUrl, expiresInDays } = payload;
-
-  return htmlShell([
-    bodyParagraph("Workspace invitation."),
+  return [
+    paragraph("Workspace invitation."),
     ctaBox({
       label: "JOIN",
       href: acceptUrl,
       padding: "20px 24px",
       fontSize: "16px",
     }),
-    metaRow("From", escapeHtml(inviterName), "tight"),
-    metaRow("Workspace", escapeHtml(orgName), "tight"),
-    metaRow("Role", role, "tight"),
-    metaRow("Expires in", `${expiresInDays} days`, "normal"),
+    keyValue("From", inviterName),
+    keyValue("Workspace", orgName),
+    keyValue("Role", role),
+    keyValue("Expires in", `${expiresInDays} days`, "normal"),
     footer(`This invitation was sent via ${COMPANY_NAME}.`, NOTICE),
-    signatureLine(),
-  ]);
+    signature(),
+  ];
 }

package/src/email/render/ownership-transfer-completed.ts

@@ -4,28 +4,30 @@
 
 import type { EmailPayloads } from "../types";
 
-import { baseTextLayout } from "./base-text";
+import { type Block, bold, footer, paragraph, signature } from "./blocks";
 
 export type OwnershipTransferCompletedPayload =
   EmailPayloads["org.ownership_transfer_completed"];
 
-export function renderOwnershipTransferCompletedBody(
+export function renderOwnershipTransferCompleted(
   payload: OwnershipTransferCompletedPayload,
-): string {
+): Block[] {
   const { orgName, newOwnerEmail } = payload;
 
-  const sections: string[] = [];
-  sections.push(
-    `The ownership of "${orgName}" has been transferred to ${newOwnerEmail}.`,
-  );
-  sections.push("");
-  sections.push(
-    "You are no longer the owner of this workspace, but you remain an admin.",
-  );
-  sections.push("");
-  sections.push(
-    "If you did not authorize this transfer, please contact support immediately.",
-  );
-
-  return baseTextLayout(sections.join("\n"));
+  return [
+    paragraph([
+      "The ownership of ",
+      bold(`"${orgName}"`),
+      " has been transferred to ",
+      bold(newOwnerEmail),
+      ".",
+    ]),
+    paragraph(
+      "You are no longer the owner of this workspace, but you remain an admin.",
+    ),
+    footer(
+      "If you did not authorize this transfer, please contact support immediately.",
+    ),
+    signature(),
+  ];
 }

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

@@ -4,33 +4,48 @@
 
 import type { EmailPayloads } from "../types";
 
-import { baseTextLayout } from "./base-text";
-import { textQuote } from "./blocks";
+import {
+  type Block,
+  bold,
+  chatUser,
+  ctaBox,
+  footer,
+  keyValue,
+  paragraph,
+  signature,
+} from "./blocks";
 
 export type OwnershipTransferPayload = EmailPayloads["org.ownership_transfer"];
 
-export function renderOwnershipTransferBody(
+export function renderOwnershipTransfer(
   payload: OwnershipTransferPayload,
-): string {
+): Block[] {
   const { orgName, acceptUrl, expiresInDays, note } = payload;
 
-  const sections: string[] = [];
-  sections.push(`You have been invited to become the owner of "${orgName}".`);
-
-  if (note) {
-    sections.push("");
-    sections.push(textQuote("Message from the current owner", note));
-  }
-
-  sections.push("");
-  sections.push("To accept this invitation, please click the link below:");
-  sections.push(acceptUrl);
-  sections.push("");
-  sections.push(`This invitation will expire in ${expiresInDays} days.`);
-  sections.push("");
-  sections.push(
-    "If you did not expect this invitation, you can safely ignore this email.",
+  const blocks: Block[] = [
+    paragraph([
+      "You have been invited to become the owner of ",
+      bold(`"${orgName}"`),
+      ".",
+    ]),
+  ];
+
+  if (note) blocks.push(chatUser(note, "Message from the current owner"));
+
+  blocks.push(
+    ctaBox({
+      label: "ACCEPT",
+      href: acceptUrl,
+      padding: "16px 24px",
+      fontSize: "16px",
+      maxWidth: "220px",
+    }),
+    keyValue("Expires in", `${expiresInDays} days`, "normal"),
+    footer(
+      "If you did not expect this invitation, you can safely ignore this email.",
+    ),
+    signature(),
   );
 
-  return baseTextLayout(sections.join("\n"));
+  return blocks;
 }