@company-semantics/contracts 34.0.0 → 35.1.0

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

@@ -0,0 +1,201 @@
+/**
+ * The Slack channel is a placeholder, so what is pinned here is the contract a
+ * placeholder still owes — `supports` total and in agreement with `render`,
+ * `render` pure and reading the brand and year from the context, every element
+ * type rendering without throwing — and NOT the Block Kit wording, which is
+ * invented and expected to change when a kind is actually posted to Slack.
+ *
+ * The mrkdwn escaping IS pinned. It is the one thing here that would be a real
+ * defect rather than a fidelity gap.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import type {
+  NotificationContent,
+  NotificationElementType,
+} from "../../../content";
+import type { RenderContext } from "../../../context";
+import { slackRenderer } 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?"] },
+        { 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",
+];
+
+describe("slackRenderer", () => {
+  it("declares a stable channel id", () => {
+    expect(slackRenderer.id).toBe("slack");
+  });
+
+  it("answers supports() for every element type — the predicate is total", () => {
+    for (const type of ALL_TYPES) {
+      expect(typeof slackRenderer.supports(type), type).toBe("boolean");
+    }
+  });
+
+  it("declines only chatUnit — Block Kit cannot depict turn-taking", () => {
+    for (const type of ALL_TYPES) {
+      expect(slackRenderer.supports(type), type).toBe(type !== "chatUnit");
+    }
+  });
+
+  it("renders a content carrying every element type without throwing", () => {
+    expect(() => slackRenderer.render(CONTENT, CONTEXT)).not.toThrow();
+  });
+
+  it("omits the declined element rather than flattening it", () => {
+    const rendered = slackRenderer.render(CONTENT, CONTEXT);
+
+    expect(JSON.stringify(rendered)).not.toContain("Hello?");
+    // Eleven admitted elements, each yielding exactly one block here.
+    expect(rendered.blocks).toHaveLength(11);
+  });
+
+  it("returns its natural type — a Block Kit record, not a string", () => {
+    const rendered = slackRenderer.render(CONTENT, CONTEXT);
+
+    // `text` is the fallback Slack shows where blocks cannot render. It is
+    // metadata.title — the same field email spends as its subject.
+    expect(rendered.text).toBe("Join Acme");
+    expect(rendered.blocks.map((block) => block.type)).toEqual([
+      "image",
+      "section",
+      "section",
+      "section",
+      "section",
+      "divider",
+      "section",
+      "context",
+      "context",
+      "actions",
+      "context",
+    ]);
+  });
+
+  it("takes the hero image the SMS channel has no surface for", () => {
+    // The two stubs exist to differ: same content, no channel tags on it, and
+    // each channel keeps what it can depict.
+    expect(slackRenderer.render(CONTENT, CONTEXT).blocks).toContainEqual({
+      type: "image",
+      image_url: "https://example.test/h.png",
+      alt_text: "Acme",
+    });
+  });
+
+  it("renders a call to action with an href as a button", () => {
+    expect(slackRenderer.render(CONTENT, CONTEXT).blocks).toContainEqual({
+      type: "actions",
+      elements: [
+        {
+          type: "button",
+          text: { type: "plain_text", text: "JOIN" },
+          url: "https://example.test/j",
+        },
+      ],
+    });
+  });
+
+  it("renders a call to action without an href as text, not a button", () => {
+    // `href` absent means the label IS the payload (an OTP code). A button with
+    // no destination would be a lie about what the notification is asking for.
+    const otp: NotificationContent = {
+      metadata: { kind: "auth.otp", title: "Your code" },
+      sections: [{ elements: [{ type: "callToAction", label: "123456" }] }],
+    };
+    expect(slackRenderer.render(otp, CONTEXT).blocks).toEqual([
+      { type: "section", text: { type: "mrkdwn", text: "*123456*" } },
+    ]);
+  });
+
+  it("escapes Slack's reserved characters in user-controlled fields", () => {
+    const hostile: NotificationContent = {
+      metadata: { kind: "org.invite", title: "Join Acme" },
+      sections: [
+        { elements: [{ type: "body", text: "a & b <c> <!channel>" }] },
+      ],
+    };
+    expect(slackRenderer.render(hostile, CONTEXT).blocks).toEqual([
+      {
+        type: "section",
+        text: {
+          type: "mrkdwn",
+          text: "a &amp; b &lt;c&gt; &lt;!channel&gt;",
+        },
+      },
+    ]);
+  });
+
+  it("reads the brand and year from context, never from a clock", () => {
+    // No fake timer in this file: swapping the context moves the copyright line.
+    const pinned: RenderContext = {
+      brand: { name: "Acme", copyrightYear: 1999 },
+    };
+    expect(JSON.stringify(slackRenderer.render(CONTENT, pinned))).toContain(
+      "© 1999 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(slackRenderer.render(onBehalf, CONTEXT).blocks).toEqual([
+      {
+        type: "context",
+        elements: [{ type: "mrkdwn", text: "© 2026 Grace" }],
+      },
+    ]);
+  });
+
+  it("is pure — same inputs, same output", () => {
+    expect(slackRenderer.render(CONTENT, CONTEXT)).toEqual(
+      slackRenderer.render(CONTENT, CONTEXT),
+    );
+  });
+});

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

@@ -0,0 +1,261 @@
+/**
+ * The Slack channel (ADR-CONTRACTS-086) — a NON-FUNCTIONAL placeholder.
+ *
+ * Where `../sms` proves the content model survives the poorest channel, this one
+ * proves the other edge: a channel whose output is neither a string nor email's
+ * `{ subject, text, html }`, but a tree of typed blocks. Between the three, `Out`
+ * has been a record, a string and a different record — which is the seam property
+ * `../../renderer.ts` states in prose ("each renderer returns its natural type",
+ * no `ChannelOutput` supertype) held by real modules rather than asserted.
+ *
+ * It is a placeholder in two specific senses:
+ *
+ * - **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.** This 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, it is not generated from them, and it is invented rather
+ *   than relocated: there is no golden here, unlike `../email`.
+ *
+ * INVARIANTS:
+ * - Pure — a function of `(content, context)`. No clock, no environment, no I/O.
+ *   The brand and the copyright year come from `context.brand`.
+ * - `supports` is total, 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`.
+ * - 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";
+
+// =============================================================================
+// The Block Kit subset
+// =============================================================================
+
+/** Formatted text. `mrkdwn` is Slack's dialect, not Markdown. */
+export interface SlackMrkdwnText {
+  type: "mrkdwn";
+  text: string;
+}
+
+/** Literal text — Slack forbids `mrkdwn` inside a button label. */
+export interface SlackPlainText {
+  type: "plain_text";
+  text: string;
+}
+
+/** A paragraph. The workhorse block: most elements land here. */
+export interface SlackSectionBlock {
+  type: "section";
+  text: SlackMrkdwnText;
+}
+
+/** A rule. The one element with a native counterpart. */
+export interface SlackDividerBlock {
+  type: "divider";
+}
+
+/** An image. Field names are Slack's wire format, hence the snake_case. */
+export interface SlackImageBlock {
+  type: "image";
+  image_url: string;
+  alt_text: string;
+}
+
+/** A button. `url` absent makes it inert — see `renderElement`'s `callToAction`. */
+export interface SlackButtonElement {
+  type: "button";
+  text: SlackPlainText;
+  url?: string;
+}
+
+/** A row of buttons. */
+export interface SlackActionsBlock {
+  type: "actions";
+  elements: SlackButtonElement[];
+}
+
+/** De-emphasised small print. Slack's own device for secondary detail. */
+export interface SlackContextBlock {
+  type: "context";
+  elements: SlackMrkdwnText[];
+}
+
+/** Every block this channel can emit. */
+export type SlackBlock =
+  | SlackSectionBlock
+  | SlackDividerBlock
+  | SlackImageBlock
+  | SlackActionsBlock
+  | SlackContextBlock;
+
+/**
+ * One Slack message — this channel's natural output type.
+ *
+ * `text` is the notification-and-fallback string Slack shows where blocks cannot
+ * render (a push notification, a screen reader). It is `metadata.title`, which is
+ * the same field email spends as its subject — one content-level fact, two
+ * channel-level uses, which is why it lives on the content rather than in a
+ * channel's registry.
+ */
+export interface SlackMessage {
+  text: string;
+  blocks: SlackBlock[];
+}
+
+// =============================================================================
+// Rendering
+// =============================================================================
+
+/**
+ * Slack's three reserved characters. Everything else is literal, so — unlike
+ * HTML — this is the whole of the escaping rule.
+ */
+function escapeMrkdwn(value: string): string {
+  return value
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+/** A section carrying pre-escaped mrkdwn. */
+function section(text: string): SlackSectionBlock {
+  return { type: "section", text: { type: "mrkdwn", text } };
+}
+
+/** A context block carrying pre-escaped mrkdwn. */
+function context(text: string): SlackContextBlock {
+  return { type: "context", elements: [{ type: "mrkdwn", text }] };
+}
+
+/**
+ * One element as zero or more blocks.
+ *
+ * Zero and many are both real here — `chatUnit` yields nothing, and an element
+ * is free to become several blocks — which is why this returns an array where
+ * `../sms`'s equivalent returns a string. The switch is total over all twelve
+ * types rather than the eleven `supports` admits: the declined arm is unreachable
+ * (`render` filters on `supports` first), but writing it out is what makes the
+ * compiler prove the two lists agree. A `default` arm would silently swallow a
+ * thirteenth member of the union.
+ */
+function renderElement(
+  element: NotificationElement,
+  renderContext: RenderContext,
+): SlackBlock[] {
+  switch (element.type) {
+    case "greeting":
+      return [section(`Hi ${escapeMrkdwn(element.recipientName ?? "there")},`)];
+    case "body":
+      return [section(escapeMrkdwn(element.text))];
+    case "keyValueTable":
+      // The `:` is presentation and lives in no element (see ../../kinds/README.md).
+      return [
+        section(
+          element.rows
+            .map(
+              (row) =>
+                `*${escapeMrkdwn(row.label)}:* ${escapeMrkdwn(row.value)}`,
+            )
+            .join("\n"),
+        ),
+      ];
+    case "callToAction":
+      // `href` absent means the label IS the payload (an OTP code), so it becomes
+      // text rather than a button with a fabricated destination.
+      return element.href
+        ? [
+            {
+              type: "actions",
+              elements: [
+                {
+                  type: "button",
+                  text: { type: "plain_text", text: element.label },
+                  url: element.href,
+                },
+              ],
+            },
+          ]
+        : [section(`*${escapeMrkdwn(element.label)}*`)];
+    case "list":
+      return [
+        section(
+          element.items
+            .map((item, index) =>
+              element.ordered
+                ? `${index + 1}. ${escapeMrkdwn(item)}`
+                : `• ${escapeMrkdwn(item)}`,
+            )
+            .join("\n"),
+        ),
+      ];
+    case "divider":
+      return [{ type: "divider" }];
+    case "warning":
+      // Fieldless by design: the banner IS the content and its prominence is the
+      // channel's to choose. Slack's answer is an emoji and bold text.
+      return [section(":warning: *Security notice*")];
+    case "metadata":
+      // A context block, because this element exists to BE de-emphasisable —
+      // diagnostic detail about the request, distinct from the facts themselves.
+      return [
+        context(
+          [
+            element.label ? `*${escapeMrkdwn(element.label)}*` : "",
+            ...element.rows.map(
+              (row) => `${escapeMrkdwn(row.label)}: ${escapeMrkdwn(row.value)}`,
+            ),
+          ]
+            .filter(Boolean)
+            .join(" · "),
+        ),
+      ];
+    case "notice":
+      return [context(element.lines.map(escapeMrkdwn).join("\n"))];
+    case "signature":
+      // Both the signer fallback and the year come from the context. This is the
+      // element that used to hide a `new Date()`; here there is nowhere to hide.
+      return [
+        context(
+          `© ${renderContext.brand.copyrightYear} ${escapeMrkdwn(
+            element.signer ?? renderContext.brand.name,
+          )}`,
+        ),
+      ];
+    case "heroImage":
+      return [{ type: "image", image_url: element.src, alt_text: element.alt }];
+    case "chatUnit":
+      return [];
+  }
+}
+
+/**
+ * Slack. Sections are one message — a channel MAY split on them (three messages
+ * in a thread is a real Slack shape) but choosing to is a delivery decision, and
+ * delivery is not this package's.
+ */
+export const slackRenderer: Renderer<SlackMessage> = {
+  id: "slack",
+  /**
+   * One decline: `chatUnit`.
+   *
+   * Block Kit has no vocabulary for turn-taking. Flattening a conversation into a
+   * run of sections would drop the attribution that IS the meaning, which the
+   * content model names as the reason to decline the whole element rather than
+   * approximate it. Everything else Slack can genuinely depict — including the
+   * hero image `../sms` has no surface for, which is the point of having two
+   * stubs rather than one.
+   */
+  supports: (elementType) => elementType !== "chatUnit",
+  render: (content: NotificationContent, renderContext: RenderContext) => ({
+    text: content.metadata.title,
+    blocks: content.sections
+      .flatMap((section_) => section_.elements)
+      .filter((element) => slackRenderer.supports(element.type))
+      .flatMap((element) => renderElement(element, renderContext)),
+  }),
+};

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

@@ -0,0 +1,69 @@
+# notifications/renderers/sms/
+
+## Purpose
+
+The SMS channel (ADR-CONTRACTS-086) — `smsRenderer: Renderer<string>`. A
+**non-functional placeholder**.
+
+`../email` could satisfy `Renderer` by construction: the seam was drawn around it,
+so it proves nothing about whether the seam generalises. SMS is the test. It is
+the poorest channel this vocabulary will ever meet — no markup, no images, no
+layout, one string — and if `NotificationContent` survives being projected onto it
+without a new element, a new field or a channel tag, then the content model is
+channel-agnostic rather than email-shaped with a `Renderer` label on it.
+
+The whole channel is one `index.ts`. `../email` splits across seven modules
+because it carries real markup; a stub that sprawls is a stub pretending.
+
+## What "placeholder" means here
+
+Two senses, neither of them a TODO to be closed by tightening this file:
+
+- **It does not send.** No delivery, no segmentation into 160-character parts, no
+  phone number. A renderer renders; the rest is the backend's, and the moment it
+  appears here the seam has leaked.
+- **It is low fidelity.** The wording is invented, not relocated. Unlike
+  `../email` there are no bytes to reproduce and no golden to answer to, so the
+  first kind actually sent over SMS should expect to author its copy properly
+  rather than trust these strings.
+
+What is NOT provisional is the shape: `Out = string`, `supports` total, `render`
+pure. Those are the seam's claims, and this module is one of the two places they
+are stated by real code instead of a test double.
+
+## The three declines
+
+`supports` answers `false` for `heroImage`, `chatUnit` and `divider`. Each is a
+fact about the channel, never an edit of the notification:
+
+| element     | why                                                                                                                     |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `heroImage` | There is no image surface. Substituting `alt` would approximate the element, which answering `false` forbids.           |
+| `chatUnit`  | The turn-taking IS the meaning; a flat run of text cannot attribute a turn. The model says decline rather than flatten. |
+| `divider`   | A thematic break is a visual device and carries no content by design. SMS has no visual vocabulary to draw one with.    |
+
+Everything else is the universal subset — what survives on the poorest channel.
+Note that `metadata` and `notice` are NOT declined: they are depictable, and
+dropping them to save characters would be an editorial choice smuggled in as a
+capability claim. Capability is "can this channel depict it", not "should it".
+
+## Invariants
+
+- PURE. `render` is a function of `(content, context)` — no clock, no
+  environment, no I/O. The brand comes from `context.brand`.
+- `supports` is total over `NotificationElementType` and AGREES with `render`: a
+  declined element is omitted, never approximated and never thrown on.
+  `__tests__/index.test.ts` asserts the whole rendered string for exactly this
+  reason — a decline is only visible in what is absent.
+- `renderElement` switches over all TWELVE element types, not the nine `supports`
+  admits. The declined arms are unreachable; writing them out is what makes the
+  compiler prove the two lists agree. Do not collapse them into a `default` —
+  that would silently accept a thirteenth member of the union.
+- The signature carries no copyright year. A copyright line is a footer device and
+  an SMS has no footer — a fidelity choice, not a purity hole. The brand still
+  comes from the context.
+- 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/sms/__tests__/README.md

@@ -0,0 +1,31 @@
+# notifications/renderers/sms/\_\_tests\_\_/
+
+## Purpose
+
+Tests for the SMS channel (ADR-CONTRACTS-086).
+
+The channel is a placeholder, which changes what these tests are for. There is no
+golden and no bytes to reproduce, so `index.test.ts` does not pin the wording —
+that is invented and expected to change the first time a kind is really sent over
+SMS. It pins the contract a placeholder still owes: `supports` total and in
+agreement with `render`, `render` pure, the brand read from `RenderContext`, and a
+content carrying all twelve element types going through without throwing.
+
+## Invariants
+
+- The wording is NOT the specification. When a real SMS kind lands and rewrites
+  these strings, updating this file is expected and cheap. When `supports` and
+  `render` stop agreeing, that is a defect — the two kinds of failure must stay
+  easy to tell apart, so keep assertions about SHAPE separate from assertions
+  about copy.
+- The full-string assertion in "omits declined elements" is deliberate and must
+  stay full-string. A decline is only observable in what is ABSENT — a partial
+  match cannot see an approximated hero image or a flattened chat turn.
+- NO fake timers. The year is a field on `RenderContext`, and keeping every test
+  in this domain clock-free is the improvement ADR-CONTRACTS-086 was built to
+  deliver — do not reintroduce them (see `../../../__tests__/README.md`).
+- `ALL_TYPES` is duplicated from `../../../__tests__/renderer.test.ts` and
+  `../../email/__tests__/render.test.ts` 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.