@company-semantics/contracts 34.0.0 → 35.1.0

package/src/email/registry.ts

@@ -1,155 +0,0 @@
-/**
- * Email Kind Registry
- *
- * Central registry of all email kinds and their definitions.
- * This is the single source of truth for email metadata.
- *
- * Invariants:
- * - Every EmailKind MUST have an entry in EMAIL_KINDS
- * - Registry keys MUST match definition.kind
- * - Registry is exhaustive (satisfies Record<EmailKind, ...>)
- * - Subjects are owned here, not duplicated in templates
- *
- * @see ADR-CONT-034 for design rationale
- */
-
-import type { EmailKind } from "./types";
-
-// =============================================================================
-// Email Kind Definition
-// =============================================================================
-
-/**
- * Complete definition for an email kind.
- *
- * This interface is the schema for entries in EMAIL_KINDS registry.
- * It captures subject, rendering requirements, and domain metadata.
- *
- * Invariants:
- * - kind field MUST match the registry key
- * - subject is the authoritative source (templates import from here)
- */
-export interface EmailKindDefinition {
-  /** The email kind this definition describes */
-  kind: EmailKind;
-  /** Email subject line (single source of truth). May contain `{field}`
-   * placeholders that `renderEmail` fills from the payload (e.g. `{orgName}`);
-   * an unmatched placeholder is left verbatim. */
-  subject: string;
-  /** Whether plain text body is required */
-  plainTextRequired: boolean;
-  /** Whether HTML body is supported */
-  htmlSupported: boolean;
-}
-
-// =============================================================================
-// Registry
-// =============================================================================
-
-/**
- * EMAIL_KINDS is the authoritative registry.
- *
- * All subjects, rendering rules, and domain metadata are derived from here.
- * Backend email templates MUST use this registry for subjects
- * rather than hardcoding values.
- *
- * To add a new kind:
- * 1. Add to EmailKind union in types.ts
- * 2. Add entry to this registry
- * 3. Add payload to EmailPayloads if needed
- * 4. Implement template in backend
- */
-export const EMAIL_KINDS = {
-  "auth.otp": {
-    kind: "auth.otp",
-    subject: "Your login code for Company Semantics",
-    plainTextRequired: true,
-    htmlSupported: false,
-  },
-  "auth.magic_link": {
-    kind: "auth.magic_link",
-    subject: "Your login link",
-    plainTextRequired: true,
-    htmlSupported: false,
-  },
-  "org.invite": {
-    kind: "org.invite",
-    subject: "You've been invited to join {orgName} on Company Semantics",
-    plainTextRequired: true,
-    htmlSupported: true,
-  },
-  "org.unit_owner_granted": {
-    kind: "org.unit_owner_granted",
-    subject: "You've been added as {roleWord} to {unitName} in {orgName}",
-    plainTextRequired: true,
-    htmlSupported: true,
-  },
-  "org.ownership_transfer": {
-    kind: "org.ownership_transfer",
-    subject: "You've been invited to become a workspace owner",
-    plainTextRequired: true,
-    htmlSupported: false,
-  },
-  "org.ownership_transfer_completed": {
-    kind: "org.ownership_transfer_completed",
-    subject: "Workspace ownership has been transferred",
-    plainTextRequired: true,
-    htmlSupported: false,
-  },
-  "security.alert": {
-    kind: "security.alert",
-    subject: "Security alert for your account",
-    plainTextRequired: true,
-    htmlSupported: false,
-  },
-  "chat.shared": {
-    kind: "chat.shared",
-    subject: "A chat has been shared with you",
-    plainTextRequired: true,
-    htmlSupported: true,
-  },
-  "share.granted": {
-    kind: "share.granted",
-    subject: "Something has been shared with you",
-    plainTextRequired: true,
-    htmlSupported: true,
-  },
-  "companyMd.access_requested": {
-    kind: "companyMd.access_requested",
-    subject: "Someone requested access to a document",
-    plainTextRequired: true,
-    htmlSupported: true,
-  },
-  "companyMd.access_request_approved": {
-    kind: "companyMd.access_request_approved",
-    subject: "Your access request was approved",
-    plainTextRequired: true,
-    htmlSupported: true,
-  },
-  "companyMd.access_request_denied": {
-    kind: "companyMd.access_request_denied",
-    subject: "Your access request was reviewed",
-    plainTextRequired: true,
-    htmlSupported: true,
-  },
-} as const satisfies Record<EmailKind, EmailKindDefinition>;
-
-// =============================================================================
-// Registry Helpers
-// =============================================================================
-
-/**
- * Type-safe registry lookup.
- * Returns the definition for a given email kind.
- */
-export function getEmailKindDefinition(kind: EmailKind): EmailKindDefinition {
-  return EMAIL_KINDS[kind];
-}
-
-/**
- * Check if a string is a valid EmailKind.
- * Use at API boundaries to reject unknown kinds.
- */
-export function isValidEmailKind(kind: string): kind is EmailKind {
-  return kind in EMAIL_KINDS;
-}

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

@@ -1,71 +0,0 @@
-/**
- * Auth OTP email (login code).
- *
- * INVARIANT: the OTP value is a runtime payload field — never a literal in this
- * package. Request metadata (IP / user agent) is gated by the caller-supplied
- * `includeRequestMetadata` option (backend reads its env flag and passes it).
- */
-
-import type { EmailPayloads } from "../types";
-
-import {
-  type Block,
-  footer,
-  greeting,
-  keyValue,
-  paragraph,
-  signature,
-} from "./blocks";
-import { chatAssistant, chatCta, chatUnit } from "./chat";
-import { COMPANY_NAME } from "./constants";
-
-export type AuthOtpPayload = EmailPayloads["auth.otp"];
-
-export interface RenderOptions {
-  /** Include request IP / device details (PII; opt-in). */
-  includeRequestMetadata?: boolean;
-}
-
-export function renderAuthOtp(
-  payload: AuthOtpPayload,
-  options?: RenderOptions,
-): Block[] {
-  const { otp, expiresInMinutes, requestIp, userAgent } = payload;
-
-  const blocks: Block[] = [
-    greeting(),
-    paragraph("A login code was requested."),
-    chatUnit(
-      chatAssistant("Copy + paste this code in the login form."),
-      chatCta({ label: otp }),
-    ),
-    keyValue("Status", "Valid"),
-    keyValue(
-      "Expires in",
-      `${expiresInMinutes} ${expiresInMinutes === 1 ? "minute" : "minutes"}`,
-      "normal",
-    ),
-  ];
-
-  // PRIVACY: IP address is PII under GDPR, so this is opt-in.
-  if (options?.includeRequestMetadata && (requestIp || userAgent)) {
-    blocks.push(paragraph("Request details:", "tight"));
-    if (requestIp) blocks.push(keyValue("IP address", requestIp));
-    if (userAgent) {
-      const truncated =
-        userAgent.length > 80 ? userAgent.slice(0, 77) + "..." : userAgent;
-      blocks.push(keyValue("Device", truncated, "normal"));
-    }
-  }
-
-  blocks.push(
-    footer(
-      `This login code was sent via ${COMPANY_NAME}.`,
-      "If this wasn't you, no action is required.",
-      "none",
-    ),
-    signature(),
-  );
-
-  return blocks;
-}

package/src/email/render/blocks.ts

@@ -1,281 +0,0 @@
-/**
- * Shared email building blocks — dual-output components.
- *
- * Every component returns a `Block` (`{ html, text }`), so a template composes
- * ONE list of blocks and both surfaces derive from the same source. Principle:
- * **blocks own the styling; templates supply only content — the only allowable
- * UI is the components.** Editing a block restyles every email, HTML and plain
- * text, across the backend (real sends) and the app (Ladle preview).
- *
- * This module holds the primitives — shells, paragraphs, and the CTA box. The
- * chat unit builds on them from `./chat`; both are re-exported together from
- * `./index`, which is the surface templates and consumers import.
- *
- * INVARIANTS:
- * - Pure functions, no side effects — except `signature()`, which reads the
- *   current year (`new Date().getFullYear()`) for the copyright line.
- * - Components escape their own content; templates pass raw text (+ `bold(...)`
- *   for inline emphasis). No template hand-writes markup or raw strings.
- */
-
-import { COMPANY_NAME, MONO_FONT_STACK } from "./constants";
-import { escapeHtml } from "./escape-html";
-
-/** Shared type styling. Exported for `./chat` only — not part of the package
- * surface (`./index` does not re-export these), so components stay the one
- * place styling is decided. */
-export const MONO = `font-family: ${MONO_FONT_STACK};`;
-
-/** The single font size for every email element (HTML). Plain text is monospace
- * so it carries no size — this keeps one visual size across both surfaces. */
-export const FONT_SIZE = "13px";
-
-// =============================================================================
-// Core types
-// =============================================================================
-
-/** A rendered block — both presentations of one component. `spacing` controls
- * the plain-text gap AFTER this block ("normal" = blank line, else none). */
-export interface Block {
-  html: string;
-  text: string;
-  spacing: Spacing;
-}
-
-/** An inline segment — for in-line emphasis inside a paragraph. */
-export interface Inline {
-  html: string;
-  text: string;
-}
-
-/** Paragraph content: raw string(s) (auto-escaped for HTML) and/or `bold(...)`. */
-export type InlineContent = string | Inline | Array<string | Inline>;
-
-/** Inline emphasis segment. Emphasis is currently visually flat — it renders
- * plain (no bold) in both surfaces; the seam is kept so all inline emphasis can
- * be restyled in one place. */
-export function bold(s: string): Inline {
-  return { html: escapeHtml(s), text: s };
-}
-
-/** Title-case a display value — capitalize the first letter of each word, e.g. a
- * role like "admin" → "Admin". Leaves already-capitalized letters untouched. */
-export function titleCase(s: string): string {
-  return s.replace(/\b\w/g, (c) => c.toUpperCase());
-}
-
-/** Normalize a segment: a raw string is escaped for HTML, passed through for text. */
-function toInline(seg: string | Inline): Inline {
-  return typeof seg === "string" ? { html: escapeHtml(seg), text: seg } : seg;
-}
-
-function renderInline(content: InlineContent): { html: string; text: string } {
-  const segs = (Array.isArray(content) ? content : [content]).map(toInline);
-  return {
-    html: segs.map((s) => s.html).join(""),
-    text: segs.map((s) => s.text).join(""),
-  };
-}
-
-/** Vertical spacing options for a paragraph. */
-export type Spacing = "normal" | "tight" | "none";
-const SPACING: Record<Spacing, string> = {
-  normal: "0 0 20px 0",
-  tight: "0 0 4px 0",
-  none: "0",
-};
-
-// =============================================================================
-// Shells
-// =============================================================================
-
-/** Wrap body blocks in the shared `<!DOCTYPE>` monospace shell. */
-export function htmlShell(blocks: Block[]): string {
-  const inner = blocks
-    .map((b) => b.html)
-    .filter(Boolean)
-    .join("\n");
-  return `<!DOCTYPE html>
-<html lang="en">
-<head><meta charset="UTF-8"></head>
-<body style="${MONO} color: #1a1a1a; margin: 0; padding: 0;">
-<div style="max-width: 520px; margin: 0 auto;">
-${inner}
-</div>
-</body>
-</html>`;
-}
-
-/** Join body blocks into the plain-text email (blank-line separated per each
- * block's spacing, trailing newline). */
-export function textShell(blocks: Block[]): string {
-  let out = "";
-  blocks.forEach((b, i) => {
-    out += b.text;
-    if (i < blocks.length - 1) out += b.spacing === "normal" ? "\n\n" : "\n";
-  });
-  return out.trim() + "\n";
-}
-
-// =============================================================================
-// Paragraphs
-// =============================================================================
-
-/**
- * Email paragraph — mono (matching the body shell), 13px, configurable spacing.
- * The single paragraph primitive: greeting / keyValue / footer / signature all
- * build on it, and templates use it directly for body lines.
- */
-export function paragraph(
-  content: InlineContent,
-  spacing: Spacing = "normal",
-): Block {
-  const { html, text } = renderInline(content);
-  return {
-    html: `<p style="${MONO} font-size: ${FONT_SIZE}; margin: ${SPACING[spacing]};">${html}</p>`,
-    text,
-    spacing,
-  };
-}
-
-/** "Hi Name," greeting; falls back to "Hi there," when the name is unknown. */
-export function greeting(recipientName?: string): Block {
-  return paragraph(recipientName ? `Hi ${recipientName},` : "Hi there,");
-}
-
-/** Security banner — the "WARNING" wordmark, sits atop security emails. */
-export function security(): Block {
-  return paragraph("🆆🅰🆁🅽🅸🅽🅶");
-}
-
-/**
- * Format an ISO timestamp as "Jun 13, 2026". Pinned to en-US + UTC so the
- * output is locale-/timezone-independent and render snapshots stay
- * deterministic. Returns the raw input unchanged if it is not a parseable date.
- */
-export function formatExpiry(iso: string): string {
-  const d = new Date(iso);
-  if (Number.isNaN(d.getTime())) return iso;
-  return d.toLocaleDateString("en-US", {
-    month: "short",
-    day: "numeric",
-    year: "numeric",
-    timeZone: "UTC",
-  });
-}
-
-/** "Label: **value**" key/value row (value bold in HTML; tight by default). */
-export function keyValue(
-  label: string,
-  value: string,
-  spacing: Spacing = "tight",
-): Block {
-  return paragraph([`${label}: `, bold(value)], spacing);
-}
-
-/** Footer paragraph: first line + optional second line after a line break. */
-export function footer(
-  firstLine: string,
-  secondLine?: string,
-  spacing: Spacing = "normal",
-): Block {
-  const html = secondLine
-    ? `${escapeHtml(firstLine)}<br>${escapeHtml(secondLine)}`
-    : escapeHtml(firstLine);
-  const text = secondLine ? `${firstLine}\n${secondLine}` : firstLine;
-  return {
-    html: `<p style="${MONO} font-size: ${FONT_SIZE}; margin: ${SPACING[spacing]};">${html}</p>`,
-    text,
-    spacing,
-  };
-}
-
-/**
- * Trailing sign-off — a leading blank line, the `---` rule, then the company
- * (or custom `signer`) name. Owns the blank above the rule so every sign-off is
- * spaced identically; the block before it carries no trailing gap.
- */
-export function signature(signer: string = COMPANY_NAME): Block {
-  const line = `ⓒ ${new Date().getFullYear()} • ${signer}`;
-  const url = "https://companysemantics.ai";
-  return {
-    html: `<p style="${MONO} font-size: ${FONT_SIZE}; margin: ${SPACING.none};"><br><br><span style="color: #bbb;">/* EOM */</span><br>${escapeHtml(line)}<br><a href="${url}" target="_blank" rel="noopener noreferrer" style="color: #0047FF; text-decoration: none;">${escapeHtml(url)}</a></p>`,
-    text: `\n\n/* EOM */\n${line}\n${url}`,
-    spacing: "none",
-  };
-}
-
-/** The standard "no action required" reassurance line (content constant). */
-export const NOTICE = "If you weren't expecting this, no action is required.";
-
-/** Human phrasing per access level (share-granted, access-approved). */
-export const ACCESS_PHRASE: Record<"editor" | "commenter" | "viewer", string> =
-  {
-    editor: "can edit",
-    commenter: "can comment",
-    viewer: "can view",
-  };
-
-// =============================================================================
-// CTA box
-// =============================================================================
-
-/** Options for the `>> LABEL <<` call-to-action box. Styling is component-owned
- * (the only allowable UI is the component) — callers supply only content. */
-export interface CtaBoxOptions {
-  /** Text between the chevrons (already display-safe). */
-  label: string;
-  /** When present, the label links to this URL (and the URL rides under the
-   * plain-text box). */
-  href?: string;
-}
-
-/** Padding columns on each side of the `>> LABEL <<` line in the ASCII box. */
-const CTA_BOX_PAD = 3;
-
-/** `>> LABEL <<` ASCII box (`*` corners): 3 lines, sized to the label. */
-function asciiCtaBox(label: string): string {
-  const pad = " ".repeat(CTA_BOX_PAD);
-  const inner = `${pad}>> ${label} <<${pad}`;
-  const border = `*${"-".repeat(inner.length)}*`;
-  return [border, `|${inner}|`, border].join("\n");
-}
-
-/** The bordered `>> LABEL <<` button (HTML table + ascii text), with `margin` on
- * the table. `ctaBox` wraps it as a standalone block; a chat unit embeds it
- * (hence the export — internal to the render layer, not re-exported by `./index`). */
-export function ctaButton(
-  opts: CtaBoxOptions,
-  margin: string,
-): { html: string; text: string } {
-  const { label, href } = opts;
-
-  const tableStyle = `display: inline-block; border: 1px solid #666; border-radius: 2px; margin: ${margin}; max-width: 220px;`;
-  const tdStyle = `padding: 16px 24px; text-align: center; ${MONO} font-size: ${FONT_SIZE};`;
-
-  // Underline only the label text (not the chevrons/spaces), and only when linked.
-  const labelHtml = href
-    ? `<span style="text-decoration: underline;">${escapeHtml(label)}</span>`
-    : escapeHtml(label);
-  const chevrons = `&gt;&gt; ${labelHtml} &lt;&lt;`;
-  const inner = href
-    ? `<a href="${href}" style="color: #0047FF; text-decoration: none;">${chevrons}</a>`
-    : chevrons;
-
-  const html = `<table cellpadding="0" cellspacing="0" border="0" style="${tableStyle}">
-  <tr><td style="${tdStyle}">
-    ${inner}
-  </td></tr>
-</table>`;
-
-  const text = href ? `${asciiCtaBox(label)}\n\n${href}` : asciiCtaBox(label);
-
-  return { html, text };
-}
-
-/** The bordered `>> LABEL <<` CTA box (OTP / JOIN / OPEN / VIEW TEAM / …). When
- * `href` is given, HTML links the label and plain text prints the URL below. */
-export function ctaBox(opts: CtaBoxOptions): Block {
-  const { html, text } = ctaButton(opts, "0 0 20px 0");
-  return { html, text, spacing: "normal" };
-}

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

@@ -1,35 +0,0 @@
-/**
- * Chat-shared email (someone shared a chat).
- */
-
-import type { EmailPayloads } from "../types";
-
-import {
-  type Block,
-  footer,
-  greeting,
-  NOTICE,
-  paragraph,
-  signature,
-} from "./blocks";
-import { chatAssistant, chatCta, chatDots, chatUnit, chatUser } from "./chat";
-import { COMPANY_NAME } from "./constants";
-
-export type ChatSharedPayload = EmailPayloads["chat.shared"];
-
-export function renderChatShared(payload: ChatSharedPayload): Block[] {
-  const { chatTitle, shareUrl, previewText, sharedByName } = payload;
-
-  return [
-    greeting(),
-    paragraph("A chat was shared with you."),
-    chatUnit(
-      chatUser(chatTitle, sharedByName),
-      ...(previewText ? [chatAssistant(previewText)] : []),
-      chatDots(),
-      chatCta({ label: "SEE MORE", href: shareUrl }),
-    ),
-    footer(`This share was sent via ${COMPANY_NAME}.`, NOTICE, "none"),
-    signature(),
-  ];
-}

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

@@ -1,42 +0,0 @@
-/**
- * Company.md access-approved email (sent to the requester).
- */
-
-import type { EmailPayloads } from "../types";
-
-import {
-  ACCESS_PHRASE,
-  type Block,
-  footer,
-  greeting,
-  keyValue,
-  paragraph,
-  signature,
-} from "./blocks";
-import { chatAssistant, chatCta, chatUnit } from "./chat";
-import { COMPANY_NAME } from "./constants";
-
-export type AccessApprovedPayload =
-  EmailPayloads["companyMd.access_request_approved"];
-
-export function renderAccessApproved(payload: AccessApprovedPayload): Block[] {
-  const { approverName, docTitle, accessLevel, docUrl } = payload;
-
-  return [
-    greeting(),
-    paragraph("Your access request was approved."),
-    chatUnit(
-      chatAssistant("Open to view."),
-      chatCta({ label: "OPEN", href: docUrl }),
-    ),
-    keyValue("Document", `"${docTitle}"`),
-    keyValue("Access", ACCESS_PHRASE[accessLevel]),
-    keyValue("Approved by", approverName, "normal"),
-    footer(
-      `This notification was sent via ${COMPANY_NAME}.`,
-      "Access is now active.",
-      "none",
-    ),
-    signature(),
-  ];
-}

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

@@ -1,43 +0,0 @@
-/**
- * Company.md access-denied email (sent to the requester). No CTA.
- */
-
-import type { EmailPayloads } from "../types";
-
-import {
-  type Block,
-  footer,
-  greeting,
-  keyValue,
-  paragraph,
-  signature,
-} from "./blocks";
-import { chatUnit, chatUser } from "./chat";
-import { COMPANY_NAME } from "./constants";
-
-export type AccessDeniedPayload =
-  EmailPayloads["companyMd.access_request_denied"];
-
-export function renderAccessDenied(payload: AccessDeniedPayload): Block[] {
-  const { approverName, docTitle, reason } = payload;
-
-  const blocks: Block[] = [
-    greeting(),
-    paragraph("Your access request was declined."),
-  ];
-
-  if (reason) blocks.push(chatUnit(chatUser(reason, approverName)));
-
-  blocks.push(
-    keyValue("Document", `"${docTitle}"`),
-    keyValue("Declined by", approverName, "normal"),
-    footer(
-      `This notification was sent via ${COMPANY_NAME}.`,
-      "This request is now closed.",
-      "none",
-    ),
-    signature(),
-  );
-
-  return blocks;
-}

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

@@ -1,46 +0,0 @@
-/**
- * Company.md access-requested email (sent to the doc owner).
- */
-
-import type { EmailPayloads } from "../types";
-
-import {
-  type Block,
-  footer,
-  greeting,
-  keyValue,
-  paragraph,
-  signature,
-} from "./blocks";
-import { chatAssistant, chatCta, chatUnit, chatUser } from "./chat";
-import { COMPANY_NAME } from "./constants";
-
-export type AccessRequestedPayload =
-  EmailPayloads["companyMd.access_requested"];
-
-const OWNER_NOTE = "You own this document.";
-
-export function renderAccessRequested(
-  payload: AccessRequestedPayload,
-): Block[] {
-  const { requesterName, docTitle, message, reviewUrl } = payload;
-
-  return [
-    greeting(),
-    paragraph("Someone requested document access."),
-    chatUnit(
-      message
-        ? chatUser(message, requesterName)
-        : chatAssistant("Review the request."),
-      chatCta({ label: "REVIEW", href: reviewUrl }),
-    ),
-    keyValue("From", requesterName),
-    keyValue("Document", `"${docTitle}"`, "normal"),
-    footer(
-      `This notification was sent via ${COMPANY_NAME}.`,
-      OWNER_NOTE,
-      "none",
-    ),
-    signature(),
-  ];
-}

package/src/email/render/constants.ts

@@ -1,18 +0,0 @@
-/**
- * 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";