@company-semantics/contracts 34.0.0 → 35.1.0

package/src/notifications/renderers/email/cta.ts

@@ -0,0 +1,63 @@
+/**
+ * The `>> LABEL <<` button — email's answer to a `callToAction`.
+ *
+ * Moved verbatim from the deleted `src/email/render/blocks` (ADR-CONTRACTS-086). It
+ * lives in its own module because two callers need it: a standalone
+ * `callToAction` element (`./render`) and one inside a conversation
+ * (`./chat`), which place it at different margins.
+ *
+ * INVARIANTS:
+ * - Pure, and byte-identical to what the deleted `src/email/render/blocks` emits.
+ * - `href` absent means the label IS the payload (an OTP code): the button must
+ *   not become a link, and plain text must not print a URL under it.
+ */
+
+import type { CallToAction } from "../../content";
+
+import { FONT_SIZE, MONO } from "./constants";
+import { escapeHtml } from "./escape-html";
+
+/** 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. A standalone element wraps it as its own line; a chat unit embeds
+ * it.
+ */
+export function ctaButton(
+  cta: CallToAction,
+  margin: string,
+): { html: string; text: string } {
+  const { label, href } = cta;
+
+  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 };
+}

package/src/{email/render → notifications/renderers/email}/escape-html.ts

@@ -1,5 +1,9 @@
 /**
- * HTML escaping for email templates.
+ * HTML escaping for the email channel.
+ *
+ * Moved here from the deleted `src/email/render/escape-html`
+ * (ADR-CONTRACTS-086): escaping is one channel's concern, and the channel now
+ * owns it.
  *
  * INVARIANT: every user-controlled field in an HTML variant MUST pass through
  * this before interpolation (prevents XSS in email clients).

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

@@ -0,0 +1,73 @@
+/**
+ * The email channel (ADR-CONTRACTS-086).
+ *
+ * `emailRenderer` is the first `Renderer` — email demoted from "the shape of the
+ * whole layer" to one channel among several. Everything that used to BE the
+ * render layer (the shells, the styling, the escaping, the box art) is now this
+ * directory's private business; what it exposes is a renderer and the type it
+ * returns. `src/email/` is gone, and this is what replaced it.
+ *
+ * INVARIANTS:
+ * - Pure. `render` is a function of `(content, context)` — no clock, no
+ *   environment, no I/O. The copyright year comes from
+ *   `context.brand.copyrightYear`.
+ * - Output is locked by `../../__tests__/render-snapshot.test.ts`. Byte-identity
+ *   with the old `src/email/render` was the whole constraint of the migration
+ *   and it held; ADR-CONTRACTS-087 discharged that proof once it shipped, so
+ *   this channel's markup is now free to change — reviewably, via the snapshot.
+ * - `supports` answers true for every element type: email is the rich channel,
+ *   and there is nothing in the content model it cannot depict.
+ */
+
+import type { NotificationContent, NotificationElement } from "../../content";
+import type { RenderContext } from "../../context";
+import type { Renderer } from "../../renderer";
+
+import type { Spacing } from "./constants";
+import { renderElement } from "./render";
+import { type EmailLine, htmlShell, textShell } from "./shells";
+
+/** One rendered email — the email channel's natural output type. */
+export interface RenderedEmail {
+  /** Subject line — the notification's `metadata.title`. */
+  subject: string;
+  /** Plain-text body. */
+  text: string;
+  /** HTML body (every kind is dual-output). */
+  html: string;
+}
+
+/**
+ * The gap after an element's last line.
+ *
+ * `signature` owns the blank line above its own rule, so whatever precedes it
+ * carries no trailing gap — the one positional rule the old templates stated
+ * out loud (every `footer(..., "none")` call, and `security.alert`'s Time row).
+ */
+function trailingSpacing(
+  elements: NotificationElement[],
+  index: number,
+): Spacing {
+  return elements[index + 1]?.type === "signature" ? "none" : "normal";
+}
+
+/** Email. Sections are one body — the seam email declines to split on. */
+export const emailRenderer: Renderer<RenderedEmail> = {
+  id: "email",
+  supports: () => true,
+  render: (content: NotificationContent, context: RenderContext) => {
+    const elements = content.sections
+      .flatMap((section) => section.elements)
+      .filter((element) => emailRenderer.supports(element.type));
+
+    const lines: EmailLine[] = elements.flatMap((element, index) =>
+      renderElement(element, context, trailingSpacing(elements, index)),
+    );
+
+    return {
+      subject: content.metadata.title,
+      text: textShell(lines),
+      html: htmlShell(lines),
+    };
+  },
+};

package/src/notifications/renderers/email/render.ts

@@ -0,0 +1,238 @@
+/**
+ * What each `NotificationElement` looks like as email (ADR-CONTRACTS-086).
+ *
+ * This is the deleted `src/email/render/blocks` read the other way round. That
+ * module offered templates a component per intent (`greeting()`, `keyValue()`,
+ * `footer()`) and each template chose which to call; here the CONTENT names the
+ * intent and this module is the only thing that knows the markup. The strings
+ * started as the same strings, byte-for-byte; they are free to diverge now
+ * (ADR-CONTRACTS-087) and `../../__tests__/render-snapshot.test.ts` is what
+ * makes each divergence a reviewed one.
+ *
+ * **Spacing is derived, because the content model does not carry it.** The old
+ * layer passed a `Spacing` per block, and `../../kinds` deliberately dropped it:
+ * a margin is a channel's answer. So this module has to re-derive one, and it
+ * does it with a single rule:
+ *
+ * > An element renders as one or more lines. Lines WITHIN an element hug
+ * > (`"tight"`); the element's LAST line carries the trailing gap, which is
+ * > `"normal"` — or `"none"` when a signature follows, because `signature`
+ * > owns the blank above its own rule.
+ *
+ * That rule reproduces every hand-authored spacing choice in the old templates,
+ * which is not a coincidence: "these lines are one thing, that gap separates two
+ * things" is what the authors were expressing, and the element boundaries are
+ * where they were expressing it. The one place it did NOT fall out was
+ * `security.alert`'s two-sentence paragraph, and the fix was to say so in the
+ * content (one `body` with a newline) rather than to special-case a kind here —
+ * see `../../kinds/security-alert`.
+ *
+ * INVARIANTS:
+ * - Pure. The copyright year and the brand come from `RenderContext`, never from
+ *   a clock — retiring the `new Date().getFullYear()` inside the old
+ *   `signature()`.
+ * - The `:` between a label and its value is PRESENTATION and lives in no
+ *   element (see `../../kinds/README.md`). This module puts it back, on
+ *   key/value rows and on the metadata heading.
+ * - Values arrive pre-formatted (dates, title-casing, truncation are `compose`'s
+ *   work). Nothing here re-formats a value.
+ */
+
+import type {
+  CallToAction,
+  KeyValueRow,
+  NotificationElement,
+} from "../../content";
+import type { RenderContext } from "../../context";
+
+import {
+  COMPANY_URL,
+  DESTRUCTIVE,
+  FONT_SIZE,
+  MONO,
+  SPACING,
+  type Spacing,
+} from "./constants";
+import { renderChatUnit } from "./chat";
+import { ctaButton } from "./cta";
+import { escapeHtml } from "./escape-html";
+import type { EmailLine } from "./shells";
+
+/** One `<p>` — the primitive every prose-ish element is built from. */
+function paragraph(html: string, text: string, spacing: Spacing): EmailLine {
+  return {
+    html: `<p style="${MONO} font-size: ${FONT_SIZE}; margin: ${SPACING[spacing]};">${html}</p>`,
+    text,
+    spacing,
+  };
+}
+
+/**
+ * Apply the spacing rule to one element's lines: everything but the last hugs,
+ * the last carries the element's trailing gap.
+ */
+function spaced(
+  lines: Array<{ html: string; text: string }>,
+  trailing: Spacing,
+): EmailLine[] {
+  return lines.map((line, i) =>
+    paragraph(
+      line.html,
+      line.text,
+      i === lines.length - 1 ? trailing : "tight",
+    ),
+  );
+}
+
+/** `Label: value` — the separator the content model does not carry. */
+function keyValueLine(row: KeyValueRow): { html: string; text: string } {
+  const text = `${row.label}: ${row.value}`;
+  return { html: escapeHtml(text), text };
+}
+
+/** The standalone `>> LABEL <<` box. */
+function ctaLine(cta: CallToAction, trailing: Spacing): EmailLine {
+  const { html, text } = ctaButton(cta, SPACING[trailing]);
+  return { html, text, spacing: trailing };
+}
+
+/** The trailing sign-off — a blank line, the `/* EOM *\/` rule, then the signer. */
+function signatureLine(signer: string, year: number): EmailLine {
+  const line = `ⓒ ${year} • ${signer}`;
+  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="${COMPANY_URL}" target="_blank" rel="noopener noreferrer" style="color: #0047FF; text-decoration: none;">${escapeHtml(COMPANY_URL)}</a></p>`,
+    text: `\n\n/* EOM */\n${line}\n${COMPANY_URL}`,
+    spacing: "none",
+  };
+}
+
+/**
+ * Render one element to its email lines.
+ *
+ * `trailing` is the gap after the element's last line, decided by what follows
+ * it — see the spacing rule at the top of this module.
+ */
+export function renderElement(
+  element: NotificationElement,
+  context: RenderContext,
+  trailing: Spacing,
+): EmailLine[] {
+  switch (element.type) {
+    case "greeting": {
+      const text = element.recipientName
+        ? `Hi ${element.recipientName},`
+        : "Hi there,";
+      return [paragraph(escapeHtml(text), text, trailing)];
+    }
+
+    case "body":
+      // A newline inside a body separates lines of ONE paragraph, so they hug;
+      // two paragraphs are two body elements. See `../../content.ts`.
+      return spaced(
+        element.text.split("\n").map((line) => ({
+          html: escapeHtml(line),
+          text: line,
+        })),
+        trailing,
+      );
+
+    case "keyValueTable":
+      return spaced(element.rows.map(keyValueLine), trailing);
+
+    case "metadata": {
+      // The heading's `:` is presentation: `label` is "Request details", and the
+      // colon the recipient reads is put back here.
+      const heading = element.label
+        ? [{ html: escapeHtml(`${element.label}:`), text: `${element.label}:` }]
+        : [];
+      return spaced([...heading, ...element.rows.map(keyValueLine)], trailing);
+    }
+
+    case "callToAction":
+      return [ctaLine(element, trailing)];
+
+    case "warning": {
+      // Fieldless by design — the banner IS the content, and its wording is the
+      // renderer's (see `../../content.ts`).
+      //
+      // The colour is this channel's answer to "this is a security notice", and
+      // only the HTML surface can give it: plain text has no colour, so there
+      // the banner's own glyphs carry the whole signal.
+      const text = "🆆🅰🆁🅽🅸🅽🅶";
+      return [
+        paragraph(
+          `<span style="color: ${DESTRUCTIVE};">${escapeHtml(text)}</span>`,
+          text,
+          trailing,
+        ),
+      ];
+    }
+
+    case "notice":
+      // One paragraph, `<br>` between lines — the lines are one unit, so unlike
+      // a `body` they do not become separate `<p>`s.
+      return [
+        paragraph(
+          element.lines.map(escapeHtml).join("<br>"),
+          element.lines.join("\n"),
+          trailing,
+        ),
+      ];
+
+    case "chatUnit": {
+      const { html, text } = renderChatUnit(element.items);
+      return [{ html, text, spacing: trailing }];
+    }
+
+    case "signature":
+      return [
+        signatureLine(
+          element.signer ?? context.brand.name,
+          context.brand.copyrightYear,
+        ),
+      ];
+
+    // -------------------------------------------------------------------------
+    // Below: elements no notification says yet.
+    //
+    // The old email layer had no component for any of these and no kind composes
+    // one, so — unlike everything above — there are no bytes to reproduce and the
+    // markup here is invented. `supports` still answers true:
+    // email CAN depict a list, a rule and an image, and declining them would be
+    // a lie about the channel. The first kind to use one should expect to style
+    // it properly rather than trust these.
+    // -------------------------------------------------------------------------
+
+    case "list":
+      return spaced(
+        element.items.map((item, i) => {
+          const text = `${element.ordered ? `${i + 1}.` : "•"} ${item}`;
+          return { html: escapeHtml(text), text };
+        }),
+        trailing,
+      );
+
+    case "divider":
+      return [
+        {
+          html: `<hr style="border: none; border-top: 1px solid #bbb; margin: ${SPACING[trailing]};">`,
+          text: "---",
+          spacing: trailing,
+        },
+      ];
+
+    case "heroImage":
+      return [
+        {
+          html: `<img src="${element.src}" alt="${escapeHtml(element.alt)}" style="max-width: 100%; margin: ${SPACING[trailing]};">`,
+          text: element.alt,
+          spacing: trailing,
+        },
+      ];
+
+    default: {
+      const _exhaustive: never = element;
+      return _exhaustive;
+    }
+  }
+}

package/src/notifications/renderers/email/shells.ts

@@ -0,0 +1,61 @@
+/**
+ * The email shells — the `<!DOCTYPE>` wrapper and the plain-text joiner.
+ *
+ * Moved verbatim from the deleted `src/email/render/blocks`
+ * (ADR-CONTRACTS-086). These are what make one email dual-output: `render`
+ * composes ONE list of `EmailLine`s and both surfaces derive from it, so the two
+ * can never disagree about what the email says.
+ *
+ * INVARIANTS:
+ * - Pure functions of their input lines. No clock, no environment, no I/O.
+ * - These strings are the email's actual markup, and
+ *   `../../__tests__/render-snapshot.test.ts` asserts them
+ *   character-for-character.
+ */
+
+import { MONO, type Spacing } from "./constants";
+
+/**
+ * One rendered line — both presentations of one thing the notification says,
+ * plus the gap that follows it.
+ *
+ * Named `EmailLine` rather than `Block`: `Block` was the old layer's canonical
+ * unit, and demoting it to a channel's internal detail is the point of
+ * ADR-CONTRACTS-086. One `NotificationElement` may produce several of these (a
+ * key/value table produces one per row).
+ */
+export interface EmailLine {
+  html: string;
+  text: string;
+  spacing: Spacing;
+}
+
+/** Wrap rendered lines in the shared `<!DOCTYPE>` monospace shell. */
+export function htmlShell(lines: EmailLine[]): string {
+  const inner = lines
+    .map((line) => line.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 rendered lines into the plain-text email — separated per each line's
+ * spacing, with a trailing newline.
+ */
+export function textShell(lines: EmailLine[]): string {
+  let out = "";
+  lines.forEach((line, i) => {
+    out += line.text;
+    if (i < lines.length - 1) out += line.spacing === "normal" ? "\n\n" : "\n";
+  });
+  return out.trim() + "\n";
+}

package/src/notifications/renderers/slack/README.md

@@ -0,0 +1,73 @@
+# notifications/renderers/slack/
+
+## Purpose
+
+The Slack channel (ADR-CONTRACTS-086) — `slackRenderer: Renderer<SlackMessage>`. A
+**non-functional placeholder**.
+
+Where `../sms` proves the content model survives the poorest channel, this proves
+the other edge: a channel whose output is a tree of typed blocks — neither a
+string nor email's `{ subject, text, html }`. Between the three, `Out` has been a
+record, a string and a different record, which is `../../renderer.ts`'s "each
+renderer returns its natural type" held by real modules rather than asserted about
+the type itself.
+
+The whole channel is one `index.ts` — the Block Kit subset, the escaping, and the
+renderer. `../email` splits across seven modules because it carries real markup; a
+stub that sprawls is a stub pretending.
+
+## What "placeholder" means here
+
+- **It does not send.** No token, no channel id, no `chat.postMessage`. A renderer
+  renders; delivery and the decision to deliver are the backend's.
+- **It is low fidelity.** `SlackBlock` is a minimal, hand-written subset of Block
+  Kit — enough to carry every element the channel admits, and no more. It is not
+  the Slack API's types and is not generated from them. The wording is invented
+  rather than relocated: there is no golden here, unlike `../email`.
+
+The field names are snake_case (`image_url`, `alt_text`) because Block Kit is a
+wire format and those are its names. That is deliberate, not a lapse in the
+repo's camelCase convention.
+
+## The one decline
+
+`supports` answers `false` for `chatUnit` alone. Block Kit has no vocabulary for
+turn-taking, and flattening a conversation into a run of sections drops the
+attribution that IS the meaning — which the content model names as the reason to
+decline a whole element rather than approximate it.
+
+Everything else Slack genuinely depicts, **including the `heroImage` that `../sms`
+has no surface for**. That difference is the point of shipping two stubs rather
+than one: same `NotificationContent`, no channel tags on it, three channels of
+differing capability each keeping what they can show.
+
+`metadata` and `notice` become `context` blocks — Slack's own device for
+de-emphasised small print, which is exactly what `MetadataElement` exists to be.
+
+## Invariants
+
+- PURE. `render` is a function of `(content, context)` — no clock, no
+  environment, no I/O. The brand and the copyright year come from `context.brand`.
+  `signature` is the element that used to hide a `new Date()`; here there is
+  nowhere to hide.
+- `supports` is total over `NotificationElementType` and AGREES with `render`:
+  `chatUnit` is omitted, never approximated and never thrown on.
+- Every user-controlled string reaching an mrkdwn surface passes through
+  `escapeMrkdwn` first — the same rule `../email` applies with `escapeHtml`. This
+  is the one thing in a low-fidelity stub that would be a real defect rather than
+  a fidelity gap, so `__tests__/index.test.ts` pins it.
+- `renderElement` switches over all TWELVE element types, not the eleven
+  `supports` admits. The declined arm is unreachable; writing it out is what makes
+  the compiler prove the two lists agree. Do not collapse it into a `default` —
+  that would silently swallow a thirteenth member of the union.
+- A `callToAction` with no `href` becomes text, never a button. `href` absent
+  means the label IS the payload (an OTP code); a button with no destination is a
+  lie about what the notification is asking for.
+- `SlackMessage.text` is `metadata.title` — the fallback Slack shows where blocks
+  cannot render. The same content-level fact email spends as its subject, which is
+  why it lives on the content rather than in a channel's registry.
+- 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`.
+- This channel is unreachable from `../../render.ts`'s `renderEmail` and touches
+  no parity fixture. It cannot change a sent email, and it must not acquire the
+  ability to.

package/src/notifications/renderers/slack/__tests__/README.md

@@ -0,0 +1,33 @@
+# notifications/renderers/slack/\_\_tests\_\_/
+
+## Purpose
+
+Tests for the Slack channel (ADR-CONTRACTS-086).
+
+The channel is a placeholder, so — as in `../../sms/__tests__/` — these tests do
+not pin the Block Kit wording. They pin the contract a placeholder still owes:
+`supports` total and in agreement with `render`, `render` pure, the brand and year
+read from `RenderContext`, and a content carrying all twelve element types
+rendering without throwing.
+
+One exception: the mrkdwn escaping IS pinned exactly. Everything else here is a
+fidelity gap that a real Slack kind will close; unescaped user input would be a
+real defect shipped in a published package.
+
+## Invariants
+
+- The Block Kit shape is NOT the specification. When a real Slack kind lands and
+  reworks these blocks, updating this file is expected. When `supports` and
+  `render` stop agreeing, or when escaping regresses, that is a defect — keep
+  assertions about SHAPE separate from assertions about copy so the two failures
+  stay easy to tell apart.
+- The "takes the hero image the SMS channel has no surface for" test is the
+  cross-channel claim, and it is why two stubs exist rather than one: the same
+  `NotificationContent`, carrying no channel tags, keeps different elements on
+  channels of different capability. It is not redundant with the totality loop.
+- NO fake timers. The year is a field on `RenderContext` (see
+  `../../../__tests__/README.md`).
+- `ALL_TYPES` is duplicated from the sibling suites rather than shared. The list
+  is the totality claim itself; importing it from one place would let a new
+  element type be added to the union and to the shared list in one move, with no
+  channel noticing.