@company-semantics/contracts 27.14.0 → 28.1.0

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,
-  paragraph,
+  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 {
-  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 {
+export function renderAccessApproved(payload: AccessApprovedPayload): Block[] {
   const { approverName, docTitle, accessLevel, docUrl } = payload;
 
-  return htmlShell([
+  return [
     greeting(),
-    paragraph(
-      `<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,58 +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 {
-  paragraph,
+  type Block,
+  bold,
+  chatUser,
   footer,
   greeting,
-  htmlShell,
-  chatUserBubble,
-  chatUserBoxText,
+  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(chatUserBoxText(reason, `Reason from ${approverName}`));
-  }
-
-  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(),
-    paragraph(
-      `<b>${escapeHtml(approverName)}</b> declined your request to access <b>"${escapeHtml(docTitle)}"</b>.`,
-    ),
-    reason ? chatUserBubble(reason, `Reason from ${approverName}`) : "",
-    footer(
-      `This notification was sent via ${COMPANY_NAME}.`,
-      undefined,
-      "none",
-    ),
-  ]);
+  return blocks;
 }

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

@@ -1,66 +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,
-  paragraph,
+  type Block,
+  bold,
+  chatUser,
   ctaBox,
   footer,
   greeting,
-  htmlShell,
-  chatUserBubble,
-  chatUserBoxText,
+  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(chatUserBoxText(message, `Message from ${requesterName}`));
-  }
-
-  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);
-
-  return baseTextLayout(sections.join("\n"));
-}
+  const blocks: Block[] = [
+    greeting(),
+    paragraph([
+      bold(requesterName),
+      " is requesting access to ",
+      bold(`"${docTitle}"`),
+      ".",
+    ]),
+  ];
 
-export function renderAccessRequestedHtml(
-  payload: AccessRequestedPayload,
-): string {
-  const { requesterName, docTitle, message, reviewUrl } = payload;
+  if (message) blocks.push(chatUser(message, `Message from ${requesterName}`));
 
-  return htmlShell([
-    greeting(),
-    paragraph(
-      `<b>${escapeHtml(requesterName)}</b> is requesting access to <b>"${escapeHtml(docTitle)}"</b>.`,
-    ),
-    message ? chatUserBubble(message, `Message from ${requesterName}`) : "",
+  blocks.push(
     ctaBox({
       label: "REVIEW",
       href: reviewUrl,
@@ -70,5 +48,7 @@ export function renderAccessRequestedHtml(
     }),
     footer(`This notification was sent via ${COMPANY_NAME}.`, OWNER_NOTE),
     signature(),
-  ]);
+  );
+
+  return blocks;
 }

package/src/email/render/index.ts

@@ -10,13 +10,13 @@ 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,
-  greeting,
+  textShell,
   paragraph,
+  greeting,
   keyValue,
   footer,
   signature,
@@ -24,14 +24,12 @@ export {
   ACCESS_PHRASE,
   chatDots,
   ctaBox,
-  chatUserBubble,
-  chatAssistantBubble,
-  asciiCtaBox,
-  asciiCodeBox,
-  chatDotsText,
-  chatUserBoxText,
-  chatAssistantBoxText,
-  clampMessage,
+  chatUser,
+  chatAssistant,
+  bold,
+  type Block,
+  type Inline,
+  type InlineContent,
   type Spacing,
   type CtaBoxOptions,
 } from "./blocks";
@@ -45,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,49 +1,26 @@
 /**
- * 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,
-  paragraph,
+  type Block,
   ctaBox,
   footer,
-  htmlShell,
   keyValue,
   NOTICE,
+  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 {
-  const { inviterName, orgName, role, acceptUrl, expiresInDays } = payload;
-
-  const sections: string[] = [];
-  sections.push("Workspace invitation.");
-  sections.push(asciiCtaBox("JOIN"));
-  sections.push("");
-  sections.push(acceptUrl);
-  sections.push("");
-  sections.push(`From: ${inviterName}`);
-  sections.push(`Workspace: ${orgName}`);
-  sections.push(`Role: ${role}`);
-  sections.push(`Expires in: ${expiresInDays} days`);
-  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 {
+export function renderOrgInvite(payload: OrgInvitePayload): Block[] {
   const { inviterName, orgName, role, acceptUrl, expiresInDays } = payload;
 
-  return htmlShell([
+  return [
     paragraph("Workspace invitation."),
     ctaBox({
       label: "JOIN",
@@ -51,11 +28,11 @@ export function renderOrgInviteHtml(payload: OrgInvitePayload): string {
       padding: "20px 24px",
       fontSize: "16px",
     }),
-    keyValue("From", escapeHtml(inviterName), "tight"),
-    keyValue("Workspace", escapeHtml(orgName), "tight"),
-    keyValue("Role", role, "tight"),
+    keyValue("From", inviterName),
+    keyValue("Workspace", orgName),
+    keyValue("Role", role),
     keyValue("Expires in", `${expiresInDays} days`, "normal"),
     footer(`This invitation was sent via ${COMPANY_NAME}.`, NOTICE),
     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 { chatUserBoxText } 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(chatUserBoxText(note, "Message from the current owner"));
-  }
-
-  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;
 }