@company-semantics/contracts 34.0.0 → 35.0.0

package/src/notifications/text.ts

@@ -0,0 +1,52 @@
+/**
+ * The stock wording and the value formats every kind's copy is built from
+ * (ADR-CONTRACTS-086).
+ *
+ * `compose` needs a few things that are neither the content MODEL nor any
+ * channel's markup: a reassurance line every kind ends on, the phrasing for an
+ * access level, and the two display formats the kinds agree on. They lived in
+ * the email layer's `blocks.ts` alongside the markup because that was the only
+ * layer there was. They are here because what a notification SAYS is the same
+ * on every channel — an SMS reassures in the same words email does.
+ *
+ * INVARIANTS:
+ * - Channel-agnostic. Nothing here may emit markup. The moment one of these
+ *   returns a tag, the seam ADR-CONTRACTS-086 draws is back where it started.
+ * - Pure. `formatExpiry` builds a `Date` from its ARGUMENT, which is not a clock
+ *   read; nothing here may add one.
+ * - These strings are output. The output-parity golden asserts them
+ *   byte-for-byte, so a wording change here changes a real sent email.
+ */
+
+/** The standard "no action required" reassurance line. */
+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",
+  };
+
+/** 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());
+}
+
+/**
+ * Format an ISO timestamp as "Jun 13, 2026". Pinned to en-US + UTC so the
+ * output is locale-/timezone-independent and rendered bytes 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",
+  });
+}

package/src/email/README.md

@@ -1,51 +0,0 @@
-# email/
-
-## Purpose
-
-Transactional email vocabulary **and** render layer: kind types, the subject
-registry, and the shared component system (`render/`) that both the backend
-(real sends) and the app (Ladle preview) compose. See ADR-CONTRACTS-077.
-
-## Invariants
-
-- Types + **pure** render functions only — no classes, no side effects, no
-  external imports beyond `zod` (vocabulary-guard enforced).
-- `render/blocks.ts` owns all styled markup; templates supply only content text.
-  Editing a block restyles every email — HTML and plain text — in both repos.
-- `renderEmail(kind, payload, options?)` is the single dispatcher; subject comes
-  from `EMAIL_KINDS`, never hardcoded in a template.
-- `EmailKind` union MUST match keys in `EMAIL_KINDS` registry.
-- OTP values MUST NEVER appear as literals in contracts (security: logged if
-  leaked) — they are runtime payload fields only.
-- Every user-controlled field in an HTML variant MUST pass through `escapeHtml`.
-- Rendered output is locked by `render/__tests__/render-snapshot.test.ts`
-  (production-parity markup — a snapshot change means a real email changed).
-- Unknown email kinds MUST be rejected at API boundaries via `isValidEmailKind()`.
-
-<!-- BEGIN GENERATED: readme-public-api — derived from code by `pnpm readme-api`. Do not edit. -->
-
-## Public API
-
-- `EMAIL_KINDS` — EMAILKINDS is the authoritative registry.
-- `EmailKind` _(type)_ — EmailKind identifies the type of transactional email.
-- `EmailKindDefinition` _(type)_ — Complete definition for an email kind.
-- `EmailPayloads` _(type)_ — Type-safe payload mapping for each email kind.
-- `SendEmailInput` _(type)_ — Type-safe input for sending emails.
-- `getEmailKindDefinition` — Type-safe registry lookup.
-- `isValidEmailKind` — Check if a string is a valid EmailKind.
-
-<!-- END GENERATED: readme-public-api -->
-
-<!-- BEGIN GENERATED: readme-dependencies — derived from code by `pnpm readme-api`. Do not edit. -->
-
-## Dependencies
-
-**Internal domains:**
-
-_None._
-
-**External packages:**
-
-_None._
-
-<!-- END GENERATED: readme-dependencies -->

package/src/email/__tests__/registry.test.ts

@@ -1,161 +0,0 @@
-import { describe, it, expect } from "vitest";
-import {
-  EMAIL_KINDS,
-  getEmailKindDefinition,
-  isValidEmailKind,
-} from "../registry.js";
-
-describe("EMAIL_KINDS golden snapshot", () => {
-  it("exact values are frozen", () => {
-    expect(EMAIL_KINDS).toStrictEqual({
-      "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,
-      },
-    });
-  });
-});
-
-describe("EMAIL_KINDS registry invariants", () => {
-  it("every registry key matches its definition.kind field", () => {
-    for (const [key, def] of Object.entries(EMAIL_KINDS)) {
-      expect(def.kind).toBe(key);
-    }
-  });
-
-  it("all subjects are non-empty strings", () => {
-    for (const def of Object.values(EMAIL_KINDS)) {
-      expect(typeof def.subject).toBe("string");
-      expect(def.subject.length).toBeGreaterThan(0);
-    }
-  });
-
-  it("all entries have required boolean fields plainTextRequired and htmlSupported", () => {
-    for (const def of Object.values(EMAIL_KINDS)) {
-      expect(typeof def.plainTextRequired).toBe("boolean");
-      expect(typeof def.htmlSupported).toBe("boolean");
-    }
-  });
-});
-
-describe("getEmailKindDefinition", () => {
-  it("returns correct definition for auth.otp", () => {
-    const def = getEmailKindDefinition("auth.otp");
-    expect(def).toStrictEqual(EMAIL_KINDS["auth.otp"]);
-  });
-
-  it("returns correct definition for auth.magic_link", () => {
-    const def = getEmailKindDefinition("auth.magic_link");
-    expect(def).toStrictEqual(EMAIL_KINDS["auth.magic_link"]);
-  });
-
-  it("returns correct definition for org.invite", () => {
-    const def = getEmailKindDefinition("org.invite");
-    expect(def).toStrictEqual(EMAIL_KINDS["org.invite"]);
-  });
-
-  it("returns correct definition for security.alert", () => {
-    const def = getEmailKindDefinition("security.alert");
-    expect(def).toStrictEqual(EMAIL_KINDS["security.alert"]);
-  });
-
-  it("returns correct definition for chat.shared", () => {
-    const def = getEmailKindDefinition("chat.shared");
-    expect(def).toStrictEqual(EMAIL_KINDS["chat.shared"]);
-  });
-
-  it("return value matches registry entry exactly", () => {
-    for (const [key, expected] of Object.entries(EMAIL_KINDS)) {
-      const def = getEmailKindDefinition(key as keyof typeof EMAIL_KINDS);
-      expect(def).toBe(expected);
-    }
-  });
-});
-
-describe("isValidEmailKind", () => {
-  it("returns true for all valid email kinds", () => {
-    for (const kind of Object.keys(EMAIL_KINDS)) {
-      expect(isValidEmailKind(kind)).toBe(true);
-    }
-  });
-
-  it("returns false for unknown string", () => {
-    expect(isValidEmailKind("unknown.kind")).toBe(false);
-  });
-
-  it("returns false for empty string", () => {
-    expect(isValidEmailKind("")).toBe(false);
-  });
-
-  it("returns false for partial match", () => {
-    expect(isValidEmailKind("auth")).toBe(false);
-  });
-});

package/src/email/index.ts

@@ -1,36 +0,0 @@
-/**
- * Email Domain Barrel
- *
- * Re-exports email kind vocabulary types and registry.
- * Import from '@company-semantics/contracts/email'.
- *
- * @see ADR-CONT-034 for design rationale
- */
-
-// =============================================================================
-// Kind Types
-// =============================================================================
-
-export type { EmailKind, EmailPayloads, SendEmailInput } from "./types";
-
-// =============================================================================
-// Definition Types
-// =============================================================================
-
-export type { EmailKindDefinition } from "./registry";
-
-// =============================================================================
-// Registry
-// =============================================================================
-
-export {
-  EMAIL_KINDS,
-  getEmailKindDefinition,
-  isValidEmailKind,
-} from "./registry";
-
-// =============================================================================
-// Render Layer
-// =============================================================================
-
-export * from "./render";

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;
-}