@company-semantics/contracts 35.1.0 → 36.0.0

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

@@ -1,5 +1,5 @@
 /**
- * The Slack channel (ADR-CONTRACTS-086) — a NON-FUNCTIONAL placeholder.
+ * The Slack channel (ADR-CONTRACTS-086, ADR-CONTRACTS-090).
  *
  * 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
@@ -8,112 +8,101 @@
  * `../../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:
+ * The blocks are Slack's OWN vocabulary: `@slack/types` is the published type
+ * package behind `node-slack-sdk`, so `KnownBlock` is the same union Slack's API
+ * validates against. This channel used to hand-write a five-block approximation
+ * of Block Kit; that is what ADR-CONTRACTS-090 retires. A renderer whose output
+ * type is invented can drift from the wire format silently, and no test in this
+ * package would notice — the compiler is the only thing that can, and it can only
+ * help if the types are theirs.
+ *
+ * It is STILL non-functional in the one sense that matters most:
  *
  * - **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`.
+ *   renderer renders; delivery and the decision to deliver are the backend's
+ *   (`SlackChannelDelivery` throws `ChannelNotImplementedError` by design).
+ *
+ * What it is no longer: low fidelity. The copy is still invented rather than
+ * relocated from a shipped Slack app — there is no golden here the way `../email`
+ * has one — but the SHAPE is legitimate Block Kit and the `__tests__` pin it.
  *
  * 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`.
+ * - Escaping follows the SURFACE, not the string. `mrkdwn` is Slack's dialect and
+ *   every user-controlled string reaching one passes through `escapeMrkdwn`;
+ *   `plain_text` and `rich_text` are literal surfaces and must NOT be escaped, or
+ *   the reader sees `&`. See `escapeMrkdwn`.
+ * - Slack's documented limits are enforced here, not left to the API to reject:
+ *   a header truncates at 150 chars, section fields chunk at 10.
  * - 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 {
+  ActionsBlock,
+  ContextBlock,
+  DividerBlock,
+  HeaderBlock,
+  ImageBlock,
+  KnownBlock,
+  MrkdwnElement,
+  PlainTextElement,
+  RichTextBlock,
+  RichTextSection,
+  SectionBlock,
+} from "@slack/types";
+
 import type { NotificationContent, NotificationElement } from "../../content";
 import type { RenderContext } from "../../context";
 import type { Renderer } from "../../renderer";
 
 // =============================================================================
-// The Block Kit subset
+// Slack's documented limits
 // =============================================================================
 
-/** 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[];
-}
+/** A `header` block's text. Slack rejects the message beyond this. */
+const HEADER_MAX_CHARS = 150;
 
-/** De-emphasised small print. Slack's own device for secondary detail. */
-export interface SlackContextBlock {
-  type: "context";
-  elements: SlackMrkdwnText[];
-}
+/** Fields per `section`. A longer table chunks across sections rather than 400s. */
+const SECTION_MAX_FIELDS = 10;
 
-/** Every block this channel can emit. */
-export type SlackBlock =
-  | SlackSectionBlock
-  | SlackDividerBlock
-  | SlackImageBlock
-  | SlackActionsBlock
-  | SlackContextBlock;
+// =============================================================================
+// One Slack message
+// =============================================================================
 
 /**
- * One Slack message — this channel's natural output type.
+ * 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.
+ * `blocks` is `KnownBlock[]` — Slack's own union, not ours. `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 and this channel ALSO spends as its `header` block:
+ * one content-level fact, three 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[];
+  blocks: KnownBlock[];
 }
 
 // =============================================================================
-// Rendering
+// Surfaces
 // =============================================================================
 
 /**
- * Slack's three reserved characters. Everything else is literal, so — unlike
- * HTML — this is the whole of the escaping rule.
+ * Slack's three reserved characters, for `mrkdwn` surfaces ONLY.
+ *
+ * Everything else is literal, so — unlike HTML — this is the whole of the rule.
+ *
+ * ⚠️ Applying this to a `plain_text` or `rich_text` surface is a DEFECT, not
+ * belt-and-braces: those surfaces do not parse `&`/`<`/`>`, so an escaped string
+ * renders the entity itself and the reader sees `Acme &amp; Co`. The old
+ * hand-written subset could not express the distinction because it had no literal
+ * surfaces beyond a button label; `header` and `rich_text` make it load-bearing.
+ * `__tests__/index.test.ts` pins both halves.
  */
 function escapeMrkdwn(value: string): string {
   return value
@@ -122,21 +111,49 @@ function escapeMrkdwn(value: string): string {
     .replace(/>/g, "&gt;");
 }
 
+/** An mrkdwn text object, from an already-escaped string. */
+function mrkdwn(text: string): MrkdwnElement {
+  return { type: "mrkdwn", text };
+}
+
+/** A literal text object. Never escaped — see `escapeMrkdwn`. */
+function plainText(text: string): PlainTextElement {
+  return { type: "plain_text", text };
+}
+
 /** A section carrying pre-escaped mrkdwn. */
-function section(text: string): SlackSectionBlock {
-  return { type: "section", text: { type: "mrkdwn", text } };
+function section(text: string): SectionBlock {
+  return { type: "section", text: mrkdwn(text) };
 }
 
 /** A context block carrying pre-escaped mrkdwn. */
-function context(text: string): SlackContextBlock {
-  return { type: "context", elements: [{ type: "mrkdwn", text }] };
+function context(text: string): ContextBlock {
+  return { type: "context", elements: [mrkdwn(text)] };
+}
+
+/** A rich-text section wrapping literal text. */
+function richTextSection(text: string): RichTextSection {
+  return { type: "rich_text_section", elements: [{ type: "text", text }] };
 }
 
+/** Split into chunks of at most `size`. Slack caps several collections. */
+function chunk<T>(items: T[], size: number): T[][] {
+  const chunks: T[][] = [];
+  for (let index = 0; index < items.length; index += size) {
+    chunks.push(items.slice(index, index + size));
+  }
+  return chunks;
+}
+
+// =============================================================================
+// Rendering
+// =============================================================================
+
 /**
  * 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
+ * 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
@@ -146,27 +163,33 @@ function context(text: string): SlackContextBlock {
 function renderElement(
   element: NotificationElement,
   renderContext: RenderContext,
-): SlackBlock[] {
+): KnownBlock[] {
   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"),
+      // `fields` is Slack's own two-column device for exactly this — facts that
+      // belong together, laid out side by side. The old subset had no `fields`,
+      // so it flattened the table into `*label:* value` lines and lost the
+      // grouping that `KeyValueTable` exists to carry. The `:` was presentation
+      // and lives in no element (see ../../kinds/README.md); Slack's answer is a
+      // bold label above its value, so the colon is simply gone.
+      //
+      // Slack caps a section at ten fields; a longer table becomes more sections
+      // rather than an API rejection.
+      return chunk(element.rows, SECTION_MAX_FIELDS).map((rows) => ({
+        type: "section",
+        fields: rows.map((row) =>
+          mrkdwn(`*${escapeMrkdwn(row.label)}*\n${escapeMrkdwn(row.value)}`),
         ),
-      ];
+      }));
     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.
+      // a preformatted block — Slack's code-block surface, which renders it in a
+      // monospaced box the reader can select cleanly — rather than a button with
+      // a fabricated destination. `rich_text` is a LITERAL surface: no escaping.
       return element.href
         ? [
             {
@@ -174,24 +197,38 @@ function renderElement(
               elements: [
                 {
                   type: "button",
-                  text: { type: "plain_text", text: element.label },
+                  text: plainText(element.label),
                   url: element.href,
                 },
               ],
             },
           ]
-        : [section(`*${escapeMrkdwn(element.label)}*`)];
+        : [
+            {
+              type: "rich_text",
+              elements: [
+                {
+                  type: "rich_text_preformatted",
+                  elements: [{ type: "text", text: element.label }],
+                },
+              ],
+            },
+          ];
     case "list":
+      // A real `rich_text_list`, not bullet characters glued onto a string. Slack
+      // draws the markers, the indentation and the numbering; `ordered` maps onto
+      // its own `style`. Literal surface — no escaping.
       return [
-        section(
-          element.items
-            .map((item, index) =>
-              element.ordered
-                ? `${index + 1}. ${escapeMrkdwn(item)}`
-                : `• ${escapeMrkdwn(item)}`,
-            )
-            .join("\n"),
-        ),
+        {
+          type: "rich_text",
+          elements: [
+            {
+              type: "rich_text_list",
+              style: element.ordered ? "ordered" : "bullet",
+              elements: element.items.map(richTextSection),
+            },
+          ],
+        },
       ];
     case "divider":
       return [{ type: "divider" }];
@@ -233,6 +270,33 @@ function renderElement(
   }
 }
 
+/**
+ * The `header` block — `metadata.title`, the same fact email spends as its
+ * subject.
+ *
+ * A real Slack message leads with its headline; the old subset spent the title
+ * only on the invisible `text` fallback, so the message opened straight into "Hi
+ * there," and the reader had to infer what it was about from the body. Both uses
+ * are correct and neither replaces the other: `text` is what a push notification
+ * and a screen reader get, `header` is what the message looks like.
+ *
+ * `plain_text` is a literal surface AND Slack's only option here — a header does
+ * not parse mrkdwn — so the title is passed through unescaped and truncated to
+ * Slack's documented 150.
+ */
+function renderHeader(content: NotificationContent): HeaderBlock[] {
+  const title = content.metadata.title.trim();
+  if (!title) return [];
+  return [
+    { type: "header", text: plainText(truncate(title, HEADER_MAX_CHARS)) },
+  ];
+}
+
+/** Cut to `max` characters, marking the cut so a clipped headline reads as one. */
+function truncate(value: string, max: number): string {
+  return value.length <= max ? value : `${value.slice(0, max - 1)}…`;
+}
+
 /**
  * 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
@@ -253,9 +317,30 @@ export const slackRenderer: Renderer<SlackMessage> = {
   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)),
+    blocks: [
+      ...renderHeader(content),
+      ...content.sections
+        .flatMap((section_) => section_.elements)
+        .filter((element) => slackRenderer.supports(element.type))
+        .flatMap((element) => renderElement(element, renderContext)),
+    ],
   }),
 };
+
+/**
+ * Re-exported so a consumer can name this channel's blocks without taking its own
+ * dependency on `@slack/types`. These are Slack's types, passed through — NOT a
+ * subset of our own. Widen this list rather than redeclaring a shape.
+ */
+export type {
+  ActionsBlock,
+  ContextBlock,
+  DividerBlock,
+  HeaderBlock,
+  ImageBlock,
+  KnownBlock,
+  MrkdwnElement,
+  PlainTextElement,
+  RichTextBlock,
+  SectionBlock,
+};