@company-semantics/contracts 27.12.0 → 27.13.0

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

@@ -0,0 +1,89 @@
+/**
+ * Chat-shared email (someone shared a chat). Plain text + HTML.
+ */
+
+import type { EmailPayloads } from "../types";
+
+import { baseTextLayout } from "./base-text";
+import {
+  asciiCtaBox,
+  bodyParagraph,
+  chatAssistantBoxText,
+  chatAssistantBubble,
+  chatDots,
+  chatDotsText,
+  chatUserBoxText,
+  chatUserBubble,
+  ctaBox,
+  footer,
+  htmlShell,
+  monoParagraph,
+  NOTICE,
+  signatureLine,
+} from "./blocks";
+import {
+  COMPANY_NAME,
+  PREVIEW_TRUNCATE_LENGTH,
+  TITLE_TRUNCATE_LENGTH,
+} from "./constants";
+import { escapeHtml } from "./escape-html";
+
+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 {
+  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);
+
+  return baseTextLayout(sections.join("\n"));
+}
+
+export function renderChatSharedHtml(payload: ChatSharedPayload): string {
+  const { chatTitle, shareUrl, previewText } = payload;
+
+  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,
+    chatDots(),
+    ctaBox({
+      label: "SEE MORE",
+      href: shareUrl,
+      padding: "12px 20px",
+      fontSize: "14px",
+      maxWidth: "200px",
+    }),
+    footer(`This share was sent via ${COMPANY_NAME}.`),
+    monoParagraph(NOTICE, "tight"),
+    signatureLine(),
+  ]);
+}

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

@@ -0,0 +1,67 @@
+/**
+ * Company.md access-approved email (sent to the requester). Text + HTML.
+ */
+
+import type { EmailPayloads } from "../types";
+
+import { baseTextLayout } from "./base-text";
+import {
+  ACCESS_PHRASE,
+  asciiCtaBox,
+  bodyParagraph,
+  ctaBox,
+  footer,
+  greeting,
+  htmlShell,
+} 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 {
+  const { approverName, docTitle, accessLevel, docUrl } = payload;
+
+  return htmlShell([
+    greeting(),
+    bodyParagraph(
+      `<b>${escapeHtml(approverName)}</b> approved your request to access <b>"${escapeHtml(docTitle)}"</b> &mdash; you ${ACCESS_PHRASE[accessLevel]}.`,
+    ),
+    ctaBox({
+      label: "OPEN",
+      href: docUrl,
+      padding: "16px 24px",
+      fontSize: "16px",
+      maxWidth: "220px",
+    }),
+    footer(
+      `This notification was sent via ${COMPANY_NAME}.`,
+      undefined,
+      "none",
+    ),
+  ]);
+}

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

@@ -0,0 +1,63 @@
+/**
+ * Company.md access-denied email (sent to the requester). No CTA. Text + HTML.
+ */
+
+import type { EmailPayloads } from "../types";
+
+import { baseTextLayout } from "./base-text";
+import {
+  bodyParagraph,
+  footer,
+  greeting,
+  htmlShell,
+  quoteBlock,
+  textQuote,
+} 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 {
+  const { approverName, docTitle, reason } = payload;
+
+  const sections: string[] = [];
+  sections.push("Hi,");
+  sections.push("");
+  sections.push(
+    `${approverName} declined your request to access "${docTitle}".`,
+  );
+
+  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",
+    ),
+  ]);
+}

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

@@ -0,0 +1,79 @@
+/**
+ * Company.md access-requested email (sent to the doc owner). Text + HTML.
+ */
+
+import type { EmailPayloads } from "../types";
+
+import { baseTextLayout } from "./base-text";
+import {
+  asciiCtaBox,
+  bodyParagraph,
+  ctaBox,
+  footer,
+  greeting,
+  htmlShell,
+  quoteBlock,
+  signatureLine,
+  textQuote,
+} 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(
+  payload: AccessRequestedPayload,
+): string {
+  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));
+  }
+
+  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"));
+}
+
+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),
+        )
+      : "",
+    ctaBox({
+      label: "REVIEW",
+      href: reviewUrl,
+      padding: "16px 24px",
+      fontSize: "16px",
+      maxWidth: "220px",
+    }),
+    footer(`This notification was sent via ${COMPANY_NAME}.`, OWNER_NOTE),
+    signatureLine(),
+  ]);
+}

package/src/email/render/constants.ts

@@ -0,0 +1,24 @@
+/**
+ * Email render constants.
+ *
+ * Branding + layout constants shared by every email template. These are the
+ * single source of truth for both the backend (real sent emails) and the app
+ * (Ladle preview). `EMAIL_FROM` (SES envelope) is infra and stays in the
+ * backend, not here.
+ */
+
+/** Product name shown in footers and signatures. */
+export const COMPANY_NAME = "Company Semantics";
+
+/** Support address shown in the plain-text footer. */
+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/escape-html.ts

@@ -0,0 +1,16 @@
+/**
+ * HTML escaping for email templates.
+ *
+ * INVARIANT: every user-controlled field in an HTML variant MUST pass through
+ * this before interpolation (prevents XSS in email clients).
+ */
+
+/** Escape HTML special characters. */
+export function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}

package/src/email/render/index.ts

@@ -0,0 +1,90 @@
+/**
+ * Email render layer — the single source of truth for transactional email
+ * markup, composed by both the backend (real sends) and the app (Ladle preview).
+ *
+ * Import from `@company-semantics/contracts/email`.
+ */
+
+// Constants
+export {
+  COMPANY_NAME,
+  SUPPORT_EMAIL,
+  MONO_FONT_STACK,
+  TITLE_TRUNCATE_LENGTH,
+  PREVIEW_TRUNCATE_LENGTH,
+} from "./constants";
+
+// Primitives
+export { escapeHtml } from "./escape-html";
+export { baseTextLayout } from "./base-text";
+
+// Shared building blocks
+export {
+  htmlShell,
+  bodyParagraph,
+  greeting,
+  monoParagraph,
+  metaRow,
+  footer,
+  signatureLine,
+  NOTICE,
+  ACCESS_PHRASE,
+  chatDots,
+  ctaBox,
+  quoteBlock,
+  chatUserBubble,
+  chatAssistantBubble,
+  asciiCtaBox,
+  asciiCodeBox,
+  textQuote,
+  chatDotsText,
+  chatUserBoxText,
+  chatAssistantBoxText,
+  type Spacing,
+  type CtaBoxOptions,
+} from "./blocks";
+
+// Dispatcher
+export {
+  renderEmail,
+  IMPLEMENTED_EMAIL_KINDS,
+  type ImplementedEmailKind,
+  type RenderedEmail,
+  type RenderEmailOptions,
+} from "./render-email";
+
+// Templates
+export {
+  renderAuthOtpBody,
+  renderAuthOtpHtml,
+  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";

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

@@ -0,0 +1,61 @@
+/**
+ * Org invite email (join a workspace). Plain text + HTML.
+ */
+
+import type { EmailPayloads } from "../types";
+
+import { baseTextLayout } from "./base-text";
+import {
+  asciiCtaBox,
+  bodyParagraph,
+  ctaBox,
+  footer,
+  htmlShell,
+  metaRow,
+  NOTICE,
+  signatureLine,
+} 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(`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."),
+    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"),
+    footer(`This invitation was sent via ${COMPANY_NAME}.`, NOTICE),
+    signatureLine(),
+  ]);
+}

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

@@ -0,0 +1,31 @@
+/**
+ * Ownership-transfer-completed notice (plain text only).
+ */
+
+import type { EmailPayloads } from "../types";
+
+import { baseTextLayout } from "./base-text";
+
+export type OwnershipTransferCompletedPayload =
+  EmailPayloads["org.ownership_transfer_completed"];
+
+export function renderOwnershipTransferCompletedBody(
+  payload: OwnershipTransferCompletedPayload,
+): string {
+  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"));
+}

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

@@ -0,0 +1,36 @@
+/**
+ * Ownership-transfer invitation email (plain text only).
+ */
+
+import type { EmailPayloads } from "../types";
+
+import { baseTextLayout } from "./base-text";
+import { textQuote } from "./blocks";
+
+export type OwnershipTransferPayload = EmailPayloads["org.ownership_transfer"];
+
+export function renderOwnershipTransferBody(
+  payload: OwnershipTransferPayload,
+): string {
+  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.",
+  );
+
+  return baseTextLayout(sections.join("\n"));
+}