@company-semantics/contracts 27.12.0 → 27.13.0

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

@@ -0,0 +1,166 @@
+/**
+ * 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.
+ */
+
+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";
+
+/** Rendered email output. */
+export interface RenderedEmail {
+  /** Subject line (from the registry). */
+  subject: string;
+  /** Plain-text body. */
+  text: string;
+  /** HTML body (present only for html-supported kinds). */
+  html?: string;
+}
+
+/** Caller-supplied render options. */
+export interface RenderEmailOptions {
+  /** Include OTP request IP / device details (PII; backend gates via env). */
+  includeRequestMetadata?: boolean;
+}
+
+/** The email kinds with a render implementation. */
+export const IMPLEMENTED_EMAIL_KINDS = [
+  "auth.otp",
+  "org.invite",
+  "org.unit_owner_granted",
+  "org.ownership_transfer",
+  "org.ownership_transfer_completed",
+  "security.alert",
+  "chat.shared",
+  "share.granted",
+  "companyMd.access_requested",
+  "companyMd.access_request_approved",
+  "companyMd.access_request_denied",
+] as const satisfies readonly EmailKind[];
+
+export type ImplementedEmailKind = (typeof IMPLEMENTED_EMAIL_KINDS)[number];
+
+/**
+ * Render an email by kind. Subject comes from `EMAIL_KINDS`; `html` is present
+ * only when the template emits an HTML variant.
+ *
+ * @throws if the kind has no implementation.
+ */
+export function renderEmail<K extends ImplementedEmailKind>(
+  kind: K,
+  payload: EmailPayloads[K],
+  options?: RenderEmailOptions,
+): RenderedEmail {
+  const subject = EMAIL_KINDS[kind].subject;
+
+  switch (kind) {
+    case "auth.otp": {
+      const p = payload as EmailPayloads["auth.otp"];
+      return {
+        subject,
+        text: renderAuthOtpBody(p, options),
+        html: renderAuthOtpHtml(p),
+      };
+    }
+    case "org.invite": {
+      const p = payload as EmailPayloads["org.invite"];
+      return {
+        subject,
+        text: renderOrgInviteBody(p),
+        html: renderOrgInviteHtml(p),
+      };
+    }
+    case "org.unit_owner_granted": {
+      const p = payload as EmailPayloads["org.unit_owner_granted"];
+      return {
+        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 {
+        subject,
+        text: renderChatSharedBody(p),
+        html: renderChatSharedHtml(p),
+      };
+    }
+    case "share.granted": {
+      const p = payload as EmailPayloads["share.granted"];
+      return {
+        subject,
+        text: renderShareGrantedBody(p),
+        html: renderShareGrantedHtml(p),
+      };
+    }
+    case "companyMd.access_requested": {
+      const p = payload as EmailPayloads["companyMd.access_requested"];
+      return {
+        subject,
+        text: renderAccessRequestedBody(p),
+        html: renderAccessRequestedHtml(p),
+      };
+    }
+    case "companyMd.access_request_approved": {
+      const p = payload as EmailPayloads["companyMd.access_request_approved"];
+      return {
+        subject,
+        text: renderAccessApprovedBody(p),
+        html: renderAccessApprovedHtml(p),
+      };
+    }
+    case "companyMd.access_request_denied": {
+      const p = payload as EmailPayloads["companyMd.access_request_denied"];
+      return {
+        subject,
+        text: renderAccessDeniedBody(p),
+        html: renderAccessDeniedHtml(p),
+      };
+    }
+    default: {
+      const unimplemented: never = kind;
+      throw new Error(`Email kind not implemented: ${String(unimplemented)}`);
+    }
+  }
+}

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

@@ -0,0 +1,62 @@
+/**
+ * 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.
+ */
+
+import type { EmailPayloads } from "../types";
+
+import { baseTextLayout } from "./base-text";
+import { COMPANY_NAME } from "./constants";
+
+export type SecurityAlertPayload = EmailPayloads["security.alert"];
+export type SecurityAlertType = SecurityAlertPayload["alertType"];
+
+export const SECURITY_ALERT_TYPES = [
+  "excessive_otp_requests",
+  "unusual_login_location",
+] as const;
+
+export function renderSecurityAlertBody(payload: SecurityAlertPayload): string {
+  const { alertType, details, timestamp } = payload;
+
+  const sections: string[] = [];
+
+  switch (alertType) {
+    case "excessive_otp_requests":
+      sections.push(
+        "We detected an unusual number of login code requests for your account.",
+      );
+      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.",
+      );
+      break;
+
+    default: {
+      const _exhaustive: never = alertType;
+      throw new Error(`Unknown alert type: ${_exhaustive}`);
+    }
+  }
+
+  sections.push("");
+  sections.push(`Time: ${new Date(timestamp).toUTCString()}`);
+
+  return baseTextLayout(sections.join("\n"), `${COMPANY_NAME} Security`);
+}

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

@@ -0,0 +1,95 @@
+/**
+ * Share-granted email (an entity was shared with the recipient). Text + HTML.
+ */
+
+import type { EmailPayloads } from "../types";
+
+import { baseTextLayout } from "./base-text";
+import {
+  ACCESS_PHRASE,
+  asciiCtaBox,
+  bodyParagraph,
+  ctaBox,
+  footer,
+  greeting,
+  htmlShell,
+  NOTICE,
+  quoteBlock,
+  signatureLine,
+  textQuote,
+} 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 {
+  const {
+    granterName,
+    recipientName,
+    entityLabel,
+    entityTitle,
+    accessLevel,
+    ctaUrl,
+    message,
+  } = payload;
+
+  const entityHtml = entityTitle
+    ? `the ${escapeHtml(entityLabel)} <b>"${escapeHtml(entityTitle)}"</b>`
+    : `a ${escapeHtml(entityLabel)}`;
+
+  return htmlShell([
+    greeting(recipientName),
+    bodyParagraph(
+      `<b>${escapeHtml(granterName)}</b> shared ${entityHtml} with you &mdash; you ${ACCESS_PHRASE[accessLevel]}.`,
+    ),
+    message
+      ? quoteBlock(
+          `Message from ${escapeHtml(granterName)}:`,
+          escapeHtml(message),
+        )
+      : "",
+    ctaBox({
+      label: "OPEN",
+      href: ctaUrl,
+      padding: "16px 24px",
+      fontSize: "16px",
+      maxWidth: "220px",
+    }),
+    footer(`This notification was sent via ${COMPANY_NAME}.`, NOTICE),
+    signatureLine(),
+  ]);
+}

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

@@ -0,0 +1,79 @@
+/**
+ * Unit-owner-granted email (added to a team's unit ownership). Text + HTML.
+ */
+
+import type { EmailPayloads } from "../types";
+
+import { baseTextLayout } from "./base-text";
+import {
+  asciiCtaBox,
+  bodyParagraph,
+  ctaBox,
+  footer,
+  greeting,
+  htmlShell,
+  NOTICE,
+  quoteBlock,
+  signatureLine,
+  textQuote,
+} from "./blocks";
+import { COMPANY_NAME } from "./constants";
+import { escapeHtml } from "./escape-html";
+
+export type UnitOwnerGrantedPayload = EmailPayloads["org.unit_owner_granted"];
+
+export function renderUnitOwnerGrantedBody(
+  payload: UnitOwnerGrantedPayload,
+): string {
+  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([
+    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),
+        )
+      : "",
+    ctaBox({
+      label: "VIEW TEAM",
+      href: ctaUrl,
+      padding: "16px 24px",
+      fontSize: "16px",
+      maxWidth: "220px",
+    }),
+    footer(`This notification was sent via ${COMPANY_NAME}.`, NOTICE),
+    signatureLine(),
+  ]);
+}