@company-semantics/contracts 34.0.0 → 35.1.0

package/src/notifications/renderers/sms/__tests__/index.test.ts

@@ -0,0 +1,162 @@
+/**
+ * The SMS channel is a placeholder, so what is worth pinning is NOT its wording —
+ * that is invented and expected to change when a kind is actually sent over SMS.
+ * What is pinned here is the contract a placeholder still owes: that `supports` is
+ * total, that it AGREES with `render`, that `render` is pure and reads the brand
+ * from the context, and that a content carrying all twelve element types goes
+ * through without throwing.
+ *
+ * The one assertion on exact bytes exists to prove the declines are silent — the
+ * only way to see "omitted, never approximated" is to look at the whole string.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import type {
+  NotificationContent,
+  NotificationElementType,
+} from "../../../content";
+import type { RenderContext } from "../../../context";
+import { smsRenderer } from "../index";
+
+const CONTEXT: RenderContext = {
+  brand: { name: "Company Semantics", copyrightYear: 2026 },
+};
+
+/** Every element type, so `render` is exercised over the whole union. */
+const CONTENT: NotificationContent = {
+  metadata: { kind: "org.invite", title: "Join Acme" },
+  sections: [
+    {
+      elements: [
+        { type: "heroImage", src: "https://example.test/h.png", alt: "Acme" },
+        { type: "greeting", recipientName: "Ada" },
+        { type: "body", text: "Acme uses Company Semantics." },
+        {
+          type: "keyValueTable",
+          rows: [{ label: "Org", value: "Acme" }],
+        },
+        { type: "list", items: ["Read", "Write"] },
+        { type: "divider" },
+        { type: "warning" },
+        {
+          type: "chatUnit",
+          items: [{ type: "message", role: "user", text: "Hello?" }],
+        },
+        {
+          type: "metadata",
+          label: "Request details",
+          rows: [{ label: "IP", value: "203.0.113.7" }],
+        },
+        { type: "notice", lines: ["Not expecting this?", "No action needed."] },
+        { type: "callToAction", label: "JOIN", href: "https://example.test/j" },
+        { type: "signature" },
+      ],
+    },
+  ],
+};
+
+const ALL_TYPES: NotificationElementType[] = [
+  "greeting",
+  "body",
+  "keyValueTable",
+  "callToAction",
+  "list",
+  "divider",
+  "warning",
+  "metadata",
+  "notice",
+  "chatUnit",
+  "signature",
+  "heroImage",
+];
+
+const DECLINED: NotificationElementType[] = [
+  "heroImage",
+  "chatUnit",
+  "divider",
+];
+
+describe("smsRenderer", () => {
+  it("declares a stable channel id", () => {
+    expect(smsRenderer.id).toBe("sms");
+  });
+
+  it("answers supports() for every element type — the predicate is total", () => {
+    for (const type of ALL_TYPES) {
+      expect(typeof smsRenderer.supports(type), type).toBe("boolean");
+    }
+  });
+
+  it("declines exactly the elements it has no surface for", () => {
+    for (const type of ALL_TYPES) {
+      expect(smsRenderer.supports(type), type).toBe(!DECLINED.includes(type));
+    }
+  });
+
+  it("renders a content carrying every element type without throwing", () => {
+    expect(() => smsRenderer.render(CONTENT, CONTEXT)).not.toThrow();
+  });
+
+  it("omits declined elements rather than approximating them", () => {
+    const rendered = smsRenderer.render(CONTENT, CONTEXT);
+
+    // The whole string, because the claim is about what is ABSENT: no alt text
+    // standing in for the hero image, no flattened chat turn, no "---" rule.
+    expect(rendered).toBe(
+      [
+        "Hi Ada,",
+        "Acme uses Company Semantics.",
+        "Org: Acme",
+        "- Read",
+        "- Write",
+        "Security notice.",
+        "Request details:",
+        "IP: 203.0.113.7",
+        "Not expecting this? No action needed.",
+        "JOIN: https://example.test/j",
+        "- Company Semantics",
+      ].join("\n"),
+    );
+    expect(rendered).not.toContain("Acme uses Company Semantics.\n---");
+    expect(rendered).not.toContain("Hello?");
+    expect(rendered).not.toContain("example.test/h.png");
+  });
+
+  it("returns its natural type — a string, not a record", () => {
+    expect(typeof smsRenderer.render(CONTENT, CONTEXT)).toBe("string");
+  });
+
+  it("reads the brand from context, never from a clock or a constant", () => {
+    // No fake timer in this file, and no COMPANY_NAME import: swapping the
+    // context is enough to move the sign-off.
+    const pinned: RenderContext = {
+      brand: { name: "Acme", copyrightYear: 1999 },
+    };
+    expect(smsRenderer.render(CONTENT, pinned)).toContain("- Acme");
+  });
+
+  it("lets an element's signer override the context brand", () => {
+    const onBehalf: NotificationContent = {
+      metadata: { kind: "org.invite", title: "Join Acme" },
+      sections: [{ elements: [{ type: "signature", signer: "Grace" }] }],
+    };
+    expect(smsRenderer.render(onBehalf, CONTEXT)).toBe("- Grace");
+  });
+
+  it("renders a call to action without an href as a bare label", () => {
+    // `href` absent means the label IS the payload (an OTP code). A channel must
+    // not fabricate a destination for it.
+    const otp: NotificationContent = {
+      metadata: { kind: "auth.otp", title: "Your code" },
+      sections: [{ elements: [{ type: "callToAction", label: "123456" }] }],
+    };
+    expect(smsRenderer.render(otp, CONTEXT)).toBe("123456");
+  });
+
+  it("is pure — same inputs, same bytes", () => {
+    expect(smsRenderer.render(CONTENT, CONTEXT)).toBe(
+      smsRenderer.render(CONTENT, CONTEXT),
+    );
+  });
+});

package/src/notifications/renderers/sms/index.ts

@@ -0,0 +1,131 @@
+/**
+ * The SMS channel (ADR-CONTRACTS-086) — a NON-FUNCTIONAL placeholder.
+ *
+ * This renderer exists to prove a claim `renderers/README.md` makes: a channel is
+ * added by writing a directory here, touching no element, no kind and no
+ * definition. Email could satisfy `Renderer` by construction — the seam was drawn
+ * around it. SMS could not: it is the poorest channel this vocabulary will ever
+ * meet, so if the content model survives being projected onto a plain string with
+ * no markup, no images and no layout, the model is channel-agnostic rather than
+ * email-shaped with a `Renderer` label on it.
+ *
+ * It is a placeholder in two specific senses, and neither is a TODO to be closed
+ * by tightening this file:
+ *
+ * - **It does not send.** A renderer renders. No delivery, no segmentation into
+ *   160-character parts, no phone number — those are the backend's, and the
+ *   moment they appear here the seam has leaked.
+ * - **It is low fidelity.** The wording below is invented, not relocated: unlike
+ *   `../email`, there are no bytes to reproduce and no golden to answer to. The
+ *   first kind actually sent over SMS should expect to author its copy properly
+ *   rather than trust these strings.
+ *
+ * `Out` is `string`, not a record. That is the second seam property, stated by a
+ * real module rather than a test double: email returns `{ subject, text, html }`
+ * and an SMS is one string, and neither is coerced toward the other.
+ *
+ * INVARIANTS:
+ * - Pure — a function of `(content, context)`. No clock, no environment, no I/O.
+ *   The brand comes from `context.brand`.
+ * - `supports` is total, and agrees with `render`: the three element types it
+ *   declines are omitted, never approximated and never thrown on.
+ * - Nothing here reads `metadata.kind`. A renderer that special-cases a kind has
+ *   lost the model — the fix for a missing fact is upstream in `compose`.
+ */
+
+import type { NotificationContent, NotificationElement } from "../../content";
+import type { RenderContext } from "../../context";
+import type { Renderer } from "../../renderer";
+
+/**
+ * One element as one run of plain text, or `""` for nothing to say.
+ *
+ * The switch is total over all twelve element types rather than over the nine
+ * `supports` admits: the declined arms are unreachable — `render` filters on
+ * `supports` before calling this — but writing them out is what makes the
+ * compiler prove the two lists agree. A `default` arm would silently accept a
+ * thirteenth member of the union, which is precisely the drift this shape
+ * prevents.
+ */
+function renderElement(
+  element: NotificationElement,
+  context: RenderContext,
+): string {
+  switch (element.type) {
+    case "greeting":
+      return `Hi ${element.recipientName ?? "there"},`;
+    case "body":
+      return element.text;
+    case "keyValueTable":
+      // The `:` is presentation and lives in no element (see ../../kinds/README.md).
+      return element.rows.map((row) => `${row.label}: ${row.value}`).join("\n");
+    case "callToAction":
+      // `href` absent means the label IS the payload (an OTP code). Rendering it
+      // as a bare label is the only honest option — a channel must not fabricate
+      // a destination for it.
+      return element.href ? `${element.label}: ${element.href}` : element.label;
+    case "list":
+      return element.items
+        .map((item, index) =>
+          element.ordered ? `${index + 1}. ${item}` : `- ${item}`,
+        )
+        .join("\n");
+    case "warning":
+      // Fieldless by design: the banner IS the content, and its wording belongs
+      // to the channel. A text message has no banner, so it has a sentence.
+      return "Security notice.";
+    case "metadata":
+      return [
+        element.label ? `${element.label}:` : "",
+        ...element.rows.map((row) => `${row.label}: ${row.value}`),
+      ]
+        .filter(Boolean)
+        .join("\n");
+    case "notice":
+      // Joined with a space, not a newline: the lines are one closing remark, and
+      // an SMS has no vertical budget to spend separating them.
+      return element.lines.join(" ");
+    case "signature":
+      // The brand comes from the context — never a constant here — but the year
+      // does not appear: a copyright line is a footer device and an SMS has no
+      // footer. Dropping it is a fidelity choice, not a purity hole.
+      return `- ${element.signer ?? context.brand.name}`;
+    case "divider":
+    case "heroImage":
+    case "chatUnit":
+      return "";
+  }
+}
+
+/**
+ * SMS. Sections are one message — the seam SMS declines to split on, for now:
+ * splitting one notification into several texts is a delivery decision, and
+ * delivery is not this package's.
+ */
+export const smsRenderer: Renderer<string> = {
+  id: "sms",
+  /**
+   * The universal subset — what survives on the poorest channel.
+   *
+   * Three declines, each a fact about the channel rather than an edit of the
+   * notification:
+   * - `heroImage` — there is no image surface. Substituting `alt` would be
+   *   approximating an element, which `supports` answering `false` forbids.
+   * - `chatUnit` — the turn-taking IS the meaning, and a flat run of text cannot
+   *   attribute a turn. The content model says decline the whole element rather
+   *   than flatten it.
+   * - `divider` — a thematic break is a visual device and carries no content by
+   *   design. SMS has no visual vocabulary to draw it with.
+   */
+  supports: (elementType) =>
+    elementType !== "heroImage" &&
+    elementType !== "chatUnit" &&
+    elementType !== "divider",
+  render: (content: NotificationContent, context: RenderContext) =>
+    content.sections
+      .flatMap((section) => section.elements)
+      .filter((element) => smsRenderer.supports(element.type))
+      .map((element) => renderElement(element, context))
+      .filter(Boolean)
+      .join("\n"),
+};

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. `__tests__/render-snapshot.test.ts` locks them, 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";