@company-semantics/contracts 30.0.0 → 32.0.0

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

@@ -7,10 +7,12 @@ import type { EmailPayloads } from "../types";
 import {
   ACCESS_PHRASE,
   type Block,
-  bold,
-  ctaBox,
+  chatAssistant,
+  chatCta,
+  chatUnit,
   footer,
   greeting,
+  keyValue,
   paragraph,
   signature,
 } from "./blocks";
@@ -24,14 +26,19 @@ export function renderAccessApproved(payload: AccessApprovedPayload): Block[] {
 
   return [
     greeting(),
-    paragraph([
-      bold(approverName),
-      " approved your request to access ",
-      bold(`"${docTitle}"`),
-      ` — you ${ACCESS_PHRASE[accessLevel]}.`,
-    ]),
-    ctaBox({ label: "OPEN", href: docUrl }),
-    footer(`This notification was sent via ${COMPANY_NAME}.`),
+    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

@@ -6,10 +6,11 @@ import type { EmailPayloads } from "../types";
 
 import {
   type Block,
-  bold,
+  chatUnit,
   chatUser,
   footer,
   greeting,
+  keyValue,
   paragraph,
   signature,
 } from "./blocks";
@@ -23,18 +24,19 @@ export function renderAccessDenied(payload: AccessDeniedPayload): Block[] {
 
   const blocks: Block[] = [
     greeting(),
-    paragraph([
-      bold(approverName),
-      " declined your request to access ",
-      bold(`"${docTitle}"`),
-      ".",
-    ]),
+    paragraph("Your access request was declined."),
   ];
 
-  if (reason) blocks.push(chatUser(reason, `Reason from ${approverName}`));
+  if (reason) blocks.push(chatUnit(chatUser(reason, approverName)));
 
   blocks.push(
-    footer(`This notification was sent via ${COMPANY_NAME}.`),
+    keyValue("Document", `"${docTitle}"`),
+    keyValue("Declined by", approverName, "normal"),
+    footer(
+      `This notification was sent via ${COMPANY_NAME}.`,
+      "This request is now closed.",
+      "none",
+    ),
     signature(),
   );
 

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

@@ -6,11 +6,13 @@ import type { EmailPayloads } from "../types";
 
 import {
   type Block,
-  bold,
+  chatAssistant,
+  chatCta,
+  chatUnit,
   chatUser,
-  ctaBox,
   footer,
   greeting,
+  keyValue,
   paragraph,
   signature,
 } from "./blocks";
@@ -19,30 +21,29 @@ import { COMPANY_NAME } from "./constants";
 export type AccessRequestedPayload =
   EmailPayloads["companyMd.access_requested"];
 
-const OWNER_NOTE = "You are receiving this because you own this document.";
+const OWNER_NOTE = "You own this document.";
 
 export function renderAccessRequested(
   payload: AccessRequestedPayload,
 ): Block[] {
   const { requesterName, docTitle, message, reviewUrl } = payload;
 
-  const blocks: Block[] = [
+  return [
     greeting(),
-    paragraph([
-      bold(requesterName),
-      " is requesting access to ",
-      bold(`"${docTitle}"`),
-      ".",
-    ]),
-  ];
-
-  if (message) blocks.push(chatUser(message, requesterName));
-
-  blocks.push(
-    ctaBox({ label: "REVIEW", href: reviewUrl }),
-    footer(`This notification was sent via ${COMPANY_NAME}.`, OWNER_NOTE),
+    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(),
-  );
-
-  return blocks;
+  ];
 }

package/src/email/render/index.ts

@@ -17,6 +17,7 @@ export {
   textShell,
   paragraph,
   greeting,
+  security,
   keyValue,
   footer,
   signature,
@@ -26,8 +27,13 @@ export {
   ctaBox,
   chatUser,
   chatAssistant,
+  chatCta,
+  chatUnit,
   bold,
   type Block,
+  type ChatMessage,
+  type ChatCta,
+  type ChatItem,
   type Inline,
   type InlineContent,
   type Spacing,

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

@@ -6,28 +6,37 @@ import type { EmailPayloads } from "../types";
 
 import {
   type Block,
-  ctaBox,
+  chatAssistant,
+  chatCta,
+  chatUnit,
   footer,
+  formatExpiry,
+  greeting,
   keyValue,
   NOTICE,
   paragraph,
   signature,
+  titleCase,
 } from "./blocks";
 import { COMPANY_NAME } from "./constants";
 
 export type OrgInvitePayload = EmailPayloads["org.invite"];
 
 export function renderOrgInvite(payload: OrgInvitePayload): Block[] {
-  const { inviterName, orgName, role, acceptUrl, expiresInDays } = payload;
+  const { inviterName, orgName, role, acceptUrl, expiresAt } = payload;
 
   return [
-    paragraph("Workspace invitation."),
-    ctaBox({ label: "JOIN", href: acceptUrl }),
+    greeting(),
+    paragraph(`${orgName} uses Company Semantics.`),
+    chatUnit(
+      chatAssistant("Join to accept the invitation."),
+      chatCta({ label: "JOIN", href: acceptUrl }),
+    ),
     keyValue("From", inviterName),
     keyValue("Workspace", orgName),
-    keyValue("Role", role),
-    keyValue("Expires in", `${expiresInDays} days`, "normal"),
-    footer(`This invitation was sent via ${COMPANY_NAME}.`, NOTICE),
+    keyValue("Role", titleCase(role)),
+    keyValue("Expires", formatExpiry(expiresAt), "normal"),
+    footer(`This invitation was sent via ${COMPANY_NAME}.`, NOTICE, "none"),
     signature(),
   ];
 }

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

@@ -4,7 +4,17 @@
 
 import type { EmailPayloads } from "../types";
 
-import { type Block, bold, footer, paragraph, signature } from "./blocks";
+import {
+  type Block,
+  chatAssistant,
+  chatUnit,
+  footer,
+  greeting,
+  keyValue,
+  paragraph,
+  signature,
+} from "./blocks";
+import { COMPANY_NAME } from "./constants";
 
 export type OwnershipTransferCompletedPayload =
   EmailPayloads["org.ownership_transfer_completed"];
@@ -15,18 +25,17 @@ export function renderOwnershipTransferCompleted(
   const { orgName, newOwnerEmail } = payload;
 
   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.",
+    greeting(),
+    paragraph("Ownership was transferred."),
+    chatUnit(
+      chatAssistant("You're no longer the owner, but you remain an admin."),
     ),
+    keyValue("Workspace", orgName),
+    keyValue("New owner", newOwnerEmail, "normal"),
     footer(
-      "If you did not authorize this transfer, please contact support immediately.",
+      `This confirmation was sent via ${COMPANY_NAME}.`,
+      "If you did not authorize this, contact support immediately.",
+      "none",
     ),
     signature(),
   ];

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

@@ -6,40 +6,40 @@ import type { EmailPayloads } from "../types";
 
 import {
   type Block,
-  bold,
+  chatAssistant,
+  chatCta,
+  chatUnit,
   chatUser,
-  ctaBox,
   footer,
+  formatExpiry,
+  greeting,
   keyValue,
+  NOTICE,
   paragraph,
   signature,
 } from "./blocks";
+import { COMPANY_NAME } from "./constants";
 
 export type OwnershipTransferPayload = EmailPayloads["org.ownership_transfer"];
 
 export function renderOwnershipTransfer(
   payload: OwnershipTransferPayload,
 ): Block[] {
-  const { orgName, acceptUrl, expiresInDays, note } = payload;
-
-  const blocks: Block[] = [
-    paragraph([
-      "You have been invited to become the owner of ",
-      bold(`"${orgName}"`),
-      ".",
-    ]),
-  ];
-
-  if (note) blocks.push(chatUser(note, "the current owner"));
-
-  blocks.push(
-    ctaBox({ label: "ACCEPT", href: acceptUrl }),
-    keyValue("Expires in", `${expiresInDays} days`, "normal"),
-    footer(
-      "If you did not expect this invitation, you can safely ignore this email.",
+  const { orgName, acceptUrl, expiresAt, note, fromName } = payload;
+
+  return [
+    greeting(),
+    paragraph("You've been invited to take ownership."),
+    chatUnit(
+      note
+        ? chatUser(note, fromName)
+        : chatAssistant("Accept to take ownership."),
+      chatCta({ label: "ACCEPT", href: acceptUrl }),
     ),
+    ...(fromName ? [keyValue("From", fromName)] : []),
+    keyValue("Workspace", orgName),
+    keyValue("Expires", formatExpiry(expiresAt), "normal"),
+    footer(`This transfer was sent via ${COMPANY_NAME}.`, NOTICE, "none"),
     signature(),
-  );
-
-  return blocks;
+  ];
 }

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

@@ -64,6 +64,41 @@ 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
@@ -77,7 +112,10 @@ export function renderEmail<K extends EmailKind>(
   payload: PayloadFor<K>,
   options?: RenderEmailOptions,
 ): RenderedEmail {
-  const subject = EMAIL_KINDS[kind].subject;
+  const subject = resolveSubject(
+    EMAIL_KINDS[kind].subject,
+    subjectData(kind, payload),
+  );
 
   switch (kind) {
     case "auth.otp":

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

@@ -1,11 +1,10 @@
 /**
- * Security alert email (plain text only). Signs off with a "Security" signer.
+ * Security alert email (plain text only).
  */
 
 import type { EmailPayloads } from "../types";
 
-import { type Block, keyValue, paragraph, signature } from "./blocks";
-import { COMPANY_NAME } from "./constants";
+import { type Block, keyValue, paragraph, security, signature } from "./blocks";
 
 export type SecurityAlertPayload = EmailPayloads["security.alert"];
 export type SecurityAlertType = SecurityAlertPayload["alertType"];
@@ -18,19 +17,17 @@ export const SECURITY_ALERT_TYPES = [
 export function renderSecurityAlert(payload: SecurityAlertPayload): Block[] {
   const { alertType, details, timestamp } = payload;
 
-  const blocks: Block[] = [];
+  const blocks: Block[] = [security()];
 
   switch (alertType) {
     case "excessive_otp_requests":
       blocks.push(
-        paragraph(
-          "We detected an unusual number of login code requests for your account.",
-        ),
+        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.",
-          "tight",
+          "normal",
         ),
         paragraph("We recommend reviewing your account security."),
       );
@@ -38,12 +35,14 @@ export function renderSecurityAlert(payload: SecurityAlertPayload): Block[] {
 
     case "unusual_login_location":
       blocks.push(
-        paragraph("We detected a login attempt from an unusual location."),
+        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, please secure your account immediately.",
+          "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;
 
@@ -54,8 +53,8 @@ export function renderSecurityAlert(payload: SecurityAlertPayload): Block[] {
   }
 
   blocks.push(
-    keyValue("Time", new Date(timestamp).toUTCString(), "normal"),
-    signature(`${COMPANY_NAME} Security`),
+    keyValue("Time", new Date(timestamp).toUTCString(), "none"),
+    signature(),
   );
 
   return blocks;

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

@@ -7,12 +7,13 @@ import type { EmailPayloads } from "../types";
 import {
   ACCESS_PHRASE,
   type Block,
-  bold,
+  chatAssistant,
+  chatCta,
+  chatUnit,
   chatUser,
-  ctaBox,
   footer,
   greeting,
-  type Inline,
+  keyValue,
   NOTICE,
   paragraph,
   signature,
@@ -32,25 +33,21 @@ export function renderShareGranted(payload: ShareGrantedPayload): Block[] {
     message,
   } = payload;
 
-  const entity: Array<string | Inline> = entityTitle
-    ? [`the ${entityLabel} `, bold(`"${entityTitle}"`)]
-    : [`a ${entityLabel}`];
-
   const blocks: Block[] = [
     greeting(recipientName),
-    paragraph([
-      bold(granterName),
-      " shared ",
-      ...entity,
-      ` with you — you ${ACCESS_PHRASE[accessLevel]}.`,
-    ]),
+    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 (message) blocks.push(chatUser(message, granterName));
+  if (entityTitle) blocks.push(keyValue("Item", `"${entityTitle}"`));
 
   blocks.push(
-    ctaBox({ label: "OPEN", href: ctaUrl }),
-    footer(`This notification was sent via ${COMPANY_NAME}.`, NOTICE),
+    keyValue("Access", ACCESS_PHRASE[accessLevel], "normal"),
+    footer(`This notification was sent via ${COMPANY_NAME}.`, NOTICE, "none"),
     signature(),
   );
 

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

@@ -6,14 +6,18 @@ import type { EmailPayloads } from "../types";
 
 import {
   type Block,
-  bold,
+  chatAssistant,
+  chatCta,
+  chatUnit,
   chatUser,
-  ctaBox,
   footer,
+  formatExpiry,
   greeting,
+  keyValue,
   NOTICE,
   paragraph,
   signature,
+  titleCase,
 } from "./blocks";
 import { COMPANY_NAME } from "./constants";
 
@@ -22,28 +26,38 @@ export type UnitOwnerGrantedPayload = EmailPayloads["org.unit_owner_granted"];
 export function renderUnitOwnerGranted(
   payload: UnitOwnerGrantedPayload,
 ): Block[] {
-  const { granterName, recipientName, unitName, roleLabel, ctaUrl, message } =
-    payload;
-
-  const blocks: Block[] = [
+  const {
+    granterName,
+    recipientName,
+    unitName,
+    roleLabel,
+    ctaUrl,
+    message,
+    expiresAt,
+  } = payload;
+  const roleNoun = roleLabel === "Delegate" ? "delegate owner" : "unit owner";
+
+  return [
     greeting(recipientName),
-    paragraph([
-      bold(granterName),
-      " added you as a ",
-      bold(roleLabel),
-      " of ",
-      bold(unitName),
-      ".",
-    ]),
-  ];
-
-  if (message) blocks.push(chatUser(message, granterName));
-
-  blocks.push(
-    ctaBox({ label: "VIEW TEAM", href: ctaUrl }),
-    footer(`This notification was sent via ${COMPANY_NAME}.`, NOTICE),
+    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(),
-  );
-
-  return blocks;
+  ];
 }

package/src/email/types.ts

@@ -63,13 +63,16 @@ export interface EmailPayloads {
     orgName: string;
     role: "admin" | "member";
     acceptUrl: string;
-    expiresInDays: number;
+    /** ISO timestamp when the invitation expires. Rendered as "Expires: Jun 13, 2026". */
+    expiresAt: string;
   };
   "org.unit_owner_granted": {
     /** Display name of the person who granted access */
     granterName: string;
     /** Display name of the recipient (optional; falls back to a neutral greeting) */
     recipientName?: string;
+    /** Name of the organization / workspace (rendered in the subject) */
+    orgName: string;
     /** Name of the org unit / team the access applies to */
     unitName: string;
     /** Human-readable role label the recipient was given */
@@ -78,16 +81,20 @@ export interface EmailPayloads {
     ctaUrl: string;
     /** Optional message from the granter, shown in the email and recorded with the grant */
     message?: string;
+    /** ISO timestamp when the grant expires. Absent = permanent (formal unit owners; delegations with no expiry). Rendered as the last key/value row ("Expires: Jun 13, 2026") when present. */
+    expiresAt?: string;
   };
   "org.ownership_transfer": {
     /** Name of the organization being transferred (subject is static; org name renders in the body) */
     orgName: string;
     /** Full URL to accept the transfer (token-bearing) */
     acceptUrl: string;
-    /** How long until the invitation expires */
-    expiresInDays: number;
+    /** ISO timestamp when the invitation expires. Rendered as "Expires: Jun 13, 2026". */
+    expiresAt: string;
     /** Optional message from the current owner */
     note?: string;
+    /** Display name of the workspace owner who initiated the transfer; attributes the note bubble. Omitted for admin-initiated transfers (no workspace-owner author). */
+    fromName?: string;
   };
   "org.ownership_transfer_completed": {
     /** Name of the organization that was transferred */