@company-semantics/contracts 33.0.0 → 35.0.0

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

@@ -1,194 +0,0 @@
-/**
- * Central email dispatcher. Given a kind + payload it returns
- * `{ subject, text, html }`, pulling the subject from the registry (single
- * 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 { 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 {
-  /** Subject line (from the registry). */
-  subject: string;
-  /** Plain-text body. */
-  text: string;
-  /** HTML body (every kind is dual-output). */
-  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];
-
-/** 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, blocks: Block[]): RenderedEmail {
-  return { subject, text: textShell(blocks), html: htmlShell(blocks) };
-}
-
-/**
- * Fill `{field}` placeholders in a registry subject from the payload (e.g.
- * `{orgName}` → the payload's orgName). Unmatched/absent placeholders are left
- * verbatim, and a placeholder-free subject passes through untouched.
- */
-function resolveSubject(template: string, payload: unknown): string {
-  if (!payload || typeof payload !== "object") return template;
-  const data = payload as Record<string, unknown>;
-  return template.replace(/\{(\w+)\}/g, (whole, key) =>
-    data[key] != null ? String(data[key]) : whole,
-  );
-}
-
-/**
- * Per-kind subject data. Most kinds resolve directly against the payload; a few
- * expose a derived token the payload doesn't carry. `org.unit_owner_granted`
- * needs a short role word ("owner"/"delegate") for the subject, whereas the
- * payload's `roleLabel` is the display form ("Unit owner"/"Delegate") used in
- * the body's Role row — so it's derived here rather than mutating roleLabel.
- */
-function subjectData(kind: EmailKind, payload: unknown): unknown {
-  if (
-    kind === "org.unit_owner_granted" &&
-    payload &&
-    typeof payload === "object"
-  ) {
-    const roleLabel = (payload as { roleLabel?: string }).roleLabel;
-    return {
-      ...payload,
-      roleWord: roleLabel === "Delegate" ? "delegate owner" : "owner",
-    };
-  }
-  return payload;
-}
-
-/**
- * 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.
- */
-export function renderEmail<K extends EmailKind>(
-  kind: K,
-  payload: PayloadFor<K>,
-  options?: RenderEmailOptions,
-): RenderedEmail {
-  const subject = resolveSubject(
-    EMAIL_KINDS[kind].subject,
-    subjectData(kind, payload),
-  );
-
-  switch (kind) {
-    case "auth.otp":
-      return toEmail(
-        subject,
-        renderAuthOtp(payload as EmailPayloads["auth.otp"], options),
-      );
-    case "org.invite":
-      return toEmail(
-        subject,
-        renderOrgInvite(payload as EmailPayloads["org.invite"]),
-      );
-    case "org.unit_owner_granted":
-      return toEmail(
-        subject,
-        renderUnitOwnerGranted(
-          payload as EmailPayloads["org.unit_owner_granted"],
-        ),
-      );
-    case "org.ownership_transfer":
-      return toEmail(
-        subject,
-        renderOwnershipTransfer(
-          payload as EmailPayloads["org.ownership_transfer"],
-        ),
-      );
-    case "org.ownership_transfer_completed":
-      return toEmail(
-        subject,
-        renderOwnershipTransferCompleted(
-          payload as EmailPayloads["org.ownership_transfer_completed"],
-        ),
-      );
-    case "security.alert":
-      return toEmail(
-        subject,
-        renderSecurityAlert(payload as EmailPayloads["security.alert"]),
-      );
-    case "chat.shared":
-      return toEmail(
-        subject,
-        renderChatShared(payload as EmailPayloads["chat.shared"]),
-      );
-    case "share.granted":
-      return toEmail(
-        subject,
-        renderShareGranted(payload as EmailPayloads["share.granted"]),
-      );
-    case "companyMd.access_requested":
-      return toEmail(
-        subject,
-        renderAccessRequested(
-          payload as EmailPayloads["companyMd.access_requested"],
-        ),
-      );
-    case "companyMd.access_request_approved":
-      return toEmail(
-        subject,
-        renderAccessApproved(
-          payload as EmailPayloads["companyMd.access_request_approved"],
-        ),
-      );
-    case "companyMd.access_request_denied":
-      return toEmail(
-        subject,
-        renderAccessDenied(
-          payload as EmailPayloads["companyMd.access_request_denied"],
-        ),
-      );
-    default: {
-      // Reachable for registered-but-unimplemented kinds (e.g. auth.magic_link).
-      const unimplemented: string = kind;
-      throw new Error(`Email kind not implemented: ${unimplemented}`);
-    }
-  }
-}

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

@@ -1,61 +0,0 @@
-/**
- * Security alert email (plain text only).
- */
-
-import type { EmailPayloads } from "../types";
-
-import { type Block, keyValue, paragraph, security, signature } from "./blocks";
-
-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 renderSecurityAlert(payload: SecurityAlertPayload): Block[] {
-  const { alertType, details, timestamp } = payload;
-
-  const blocks: Block[] = [security()];
-
-  switch (alertType) {
-    case "excessive_otp_requests":
-      blocks.push(
-        paragraph("Unusual login-code activity detected."),
-        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.",
-          "normal",
-        ),
-        paragraph("We recommend reviewing your account security."),
-      );
-      break;
-
-    case "unusual_login_location":
-      blocks.push(
-        paragraph("A login from an unusual location was detected."),
-        keyValue("Details", details, "normal"),
-        paragraph("If this was you, no action is needed.", "tight"),
-        paragraph(
-          "If you didn't attempt to log in, someone may be trying to access your account.",
-          "normal",
-        ),
-        paragraph("We recommend reviewing your account security."),
-      );
-      break;
-
-    default: {
-      const _exhaustive: never = alertType;
-      throw new Error(`Unknown alert type: ${_exhaustive}`);
-    }
-  }
-
-  blocks.push(
-    keyValue("Time", new Date(timestamp).toUTCString(), "none"),
-    signature(),
-  );
-
-  return blocks;
-}

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

@@ -1,52 +0,0 @@
-/**
- * Share-granted email (an entity was shared with the recipient).
- */
-
-import type { EmailPayloads } from "../types";
-
-import {
-  ACCESS_PHRASE,
-  type Block,
-  footer,
-  greeting,
-  keyValue,
-  NOTICE,
-  paragraph,
-  signature,
-} from "./blocks";
-import { chatAssistant, chatCta, chatUnit, chatUser } from "./chat";
-import { COMPANY_NAME } from "./constants";
-
-export type ShareGrantedPayload = EmailPayloads["share.granted"];
-
-export function renderShareGranted(payload: ShareGrantedPayload): Block[] {
-  const {
-    granterName,
-    recipientName,
-    entityLabel,
-    entityTitle,
-    accessLevel,
-    ctaUrl,
-    message,
-  } = payload;
-
-  const blocks: Block[] = [
-    greeting(recipientName),
-    paragraph(`A ${entityLabel} was shared with you.`),
-    chatUnit(
-      message ? chatUser(message, granterName) : chatAssistant("Open to view."),
-      chatCta({ label: "OPEN", href: ctaUrl }),
-    ),
-    keyValue("From", granterName),
-  ];
-
-  if (entityTitle) blocks.push(keyValue("Item", `"${entityTitle}"`));
-
-  blocks.push(
-    keyValue("Access", ACCESS_PHRASE[accessLevel], "normal"),
-    footer(`This notification was sent via ${COMPANY_NAME}.`, NOTICE, "none"),
-    signature(),
-  );
-
-  return blocks;
-}

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

@@ -1,60 +0,0 @@
-/**
- * Unit-owner-granted email (added to a team's unit ownership).
- */
-
-import type { EmailPayloads } from "../types";
-
-import {
-  type Block,
-  footer,
-  formatExpiry,
-  greeting,
-  keyValue,
-  NOTICE,
-  paragraph,
-  signature,
-  titleCase,
-} from "./blocks";
-import { chatAssistant, chatCta, chatUnit, chatUser } from "./chat";
-import { COMPANY_NAME } from "./constants";
-
-export type UnitOwnerGrantedPayload = EmailPayloads["org.unit_owner_granted"];
-
-export function renderUnitOwnerGranted(
-  payload: UnitOwnerGrantedPayload,
-): Block[] {
-  const {
-    granterName,
-    recipientName,
-    unitName,
-    roleLabel,
-    ctaUrl,
-    message,
-    expiresAt,
-  } = payload;
-  const roleNoun = roleLabel === "Delegate" ? "delegate owner" : "unit owner";
-
-  return [
-    greeting(recipientName),
-    paragraph(
-      `You are now a ${roleNoun} of ${unitName}. ${roleNoun[0].toUpperCase()}${roleNoun.slice(1)}s hold authority over the team: managing team membership, doc access, strategy, and execution against goals.`,
-    ),
-    chatUnit(
-      ...(message ? [chatUser(message, granterName)] : []),
-      chatAssistant("Open the team to get started."),
-      chatCta({ label: "MANAGE TEAM", href: ctaUrl }),
-    ),
-    keyValue("From", granterName),
-    keyValue("Team", unitName),
-    keyValue(
-      "Role",
-      titleCase(roleLabel),
-      expiresAt != null ? "tight" : "normal",
-    ),
-    ...(expiresAt != null
-      ? [keyValue("Expires", formatExpiry(expiresAt), "normal")]
-      : []),
-    footer(`This notification was sent via ${COMPANY_NAME}.`, NOTICE, "none"),
-    signature(),
-  ];
-}