@company-semantics/contracts 33.0.0 → 35.0.0

package/src/notifications/content.ts

@@ -0,0 +1,249 @@
+/**
+ * Channel-agnostic notification content — the semantic model (ADR-CONTRACTS-086).
+ *
+ * `NotificationContent` is what a notification SAYS. It carries no markup, no
+ * styling and no channel names: every element names a communicative intent
+ * ("greet the recipient", "these are the facts", "this is the one action"), and
+ * a `Renderer` decides what that intent looks like on its channel. This is the
+ * old `email/render/blocks` rule — components own the styling, callers supply
+ * only content — lifted one level: the renderer owns the styling, `compose`
+ * supplies only content.
+ *
+ * The element union is deliberately FLAT. Elements do not nest into layout
+ * containers, because layout is a channel's answer rather than the
+ * notification's. `Section` groups elements a channel may want to keep together
+ * (one email body, one chat message, one push bundle) and is the only grouping
+ * this model commits to.
+ *
+ * INVARIANTS:
+ * - Types only — no markup, no styling fields, no channel names on elements.
+ * - Every element is content a renderer MAY decline to show. Capability lives on
+ *   the renderer (`supports`), never on the element.
+ * - Element names describe intent, not appearance. `Warning` is "this is a
+ *   security notice", not "render a red box".
+ */
+
+// =============================================================================
+// Shared value types
+// =============================================================================
+
+/** One `label` / `value` fact. The renderer owns the separator and alignment. */
+export interface KeyValueRow {
+  label: string;
+  value: string;
+}
+
+// =============================================================================
+// Elements
+// =============================================================================
+
+/**
+ * Address the recipient. `recipientName` absent means the name is unknown — the
+ * renderer supplies its own generic form rather than the caller inventing one.
+ */
+export interface Greeting {
+  type: "greeting";
+  recipientName?: string;
+}
+
+/**
+ * A prose paragraph — the notification's own voice.
+ *
+ * A newline separates lines WITHIN one paragraph: two sentences that read as one
+ * thought. Two paragraphs are two `body` elements. The distinction is content,
+ * not styling — which sentences belong together is the notification's to say,
+ * and only how tightly they sit is the renderer's.
+ */
+export interface Body {
+  type: "body";
+  text: string;
+}
+
+/**
+ * The notification's primary facts, as one group. Grouping is the point: a
+ * channel that renders facts as a real table (or a Slack field block) needs them
+ * together, which per-row elements could not express.
+ */
+export interface KeyValueTable {
+  type: "keyValueTable";
+  rows: KeyValueRow[];
+}
+
+/**
+ * The one action the notification is asking for. `href` absent means the label
+ * IS the payload (an OTP code), not a link — the renderer must not fabricate a
+ * destination for it.
+ */
+export interface CallToAction {
+  type: "callToAction";
+  label: string;
+  href?: string;
+}
+
+/** A sequence of items. `ordered` when the sequence itself carries meaning. */
+export interface List {
+  type: "list";
+  items: string[];
+  ordered?: boolean;
+}
+
+/** A thematic break between elements. Carries no content by design. */
+export interface Divider {
+  type: "divider";
+}
+
+/**
+ * Marks the notification as a security notice. Fieldless on purpose: the banner
+ * IS the content, and its wording and prominence belong to the renderer — the
+ * same reason `security()` in the old `email/render/blocks` took no arguments.
+ */
+export interface Warning {
+  type: "warning";
+}
+
+/**
+ * Secondary context ABOUT the request that produced this notification (request
+ * IP, device), as distinct from `KeyValueTable`, which carries the notification's
+ * own subject matter. The split is what lets a channel de-emphasise or drop
+ * diagnostic detail while still showing the facts that matter.
+ *
+ * Whether these rows exist at all is `compose`'s decision, not a renderer's —
+ * some of this is PII and is gated upstream.
+ */
+export interface MetadataElement {
+  type: "metadata";
+  /** Heading above the rows, e.g. "Request details". */
+  label?: string;
+  rows: KeyValueRow[];
+}
+
+/**
+ * The closing legal / reassurance lines ("If you weren't expecting this, no
+ * action is required."). `lines` are rendered as one unit; the renderer chooses
+ * how to separate them.
+ */
+export interface Notice {
+  type: "notice";
+  lines: string[];
+}
+
+/**
+ * The trailing sign-off. `signer` overrides the brand name from `RenderContext`
+ * for a notification sent on someone else's behalf; absent means the context's
+ * brand signs it. The copyright year comes from the context, never from a clock
+ * read inside the renderer.
+ */
+export interface Signature {
+  type: "signature";
+  signer?: string;
+}
+
+/** A leading image. `alt` is required — a text-only channel has nothing else. */
+export interface HeroImage {
+  type: "heroImage";
+  src: string;
+  alt: string;
+}
+
+// =============================================================================
+// Chat unit
+// =============================================================================
+
+/**
+ * One turn in a reproduced conversation. `from` attributes a user's message.
+ *
+ * Named `ChatTurn`, not `ChatMessage`, because the old `email/render/blocks`
+ * exported a `ChatMessage` and the email renderer imported both at once. That
+ * collision died with the directory; the name stays because it is the better one
+ * — a turn is what this IS, and renaming a published type to reclaim a freed
+ * name is churn.
+ */
+export interface ChatTurn {
+  type: "message";
+  role: "user" | "assistant";
+  text: string;
+  from?: string;
+}
+
+/** "The conversation continues" — an elision between turns. */
+export interface ChatContinuation {
+  type: "continuation";
+}
+
+/**
+ * An item inside a chat unit. A call to action inside a conversation is the same
+ * intent as a standalone one, so `CallToAction` is reused rather than mirrored.
+ */
+export type ChatUnitItem = ChatTurn | CallToAction | ChatContinuation;
+
+/**
+ * A reproduced conversation, shown as a unit. Renderers that cannot depict a
+ * conversation should decline the whole element rather than flatten it — the
+ * turn-taking is the meaning.
+ */
+export interface ChatUnit {
+  type: "chatUnit";
+  items: ChatUnitItem[];
+}
+
+// =============================================================================
+// The element union
+// =============================================================================
+
+/**
+ * Everything a notification can say, flat. Named `NotificationElement` rather
+ * than `Element` because `Element` is a DOM global — a bare export would shadow
+ * it for every consumer that imports this barrel.
+ */
+export type NotificationElement =
+  | Greeting
+  | Body
+  | KeyValueTable
+  | CallToAction
+  | List
+  | Divider
+  | Warning
+  | MetadataElement
+  | Notice
+  | ChatUnit
+  | Signature
+  | HeroImage;
+
+/** The discriminant of `NotificationElement` — what `supports` is asked about. */
+export type NotificationElementType = NotificationElement["type"];
+
+// =============================================================================
+// Content
+// =============================================================================
+
+/**
+ * A run of elements a channel should keep together. Sections are the seam at
+ * which a channel MAY split one notification into several deliverables (three
+ * chat messages, one email body); a renderer is free to ignore them.
+ */
+export interface Section {
+  elements: NotificationElement[];
+}
+
+/**
+ * Notification-level facts that are not body content.
+ *
+ * `title` is the headline, held here rather than in a channel's registry — that
+ * fusion (subject in `EMAIL_KINDS`, copy in the template) is exactly what
+ * ADR-CONTRACTS-086 splits. Email renders it as the subject; another channel
+ * renders it as a notification title, or drops it.
+ *
+ * Distinct from the `metadata` ELEMENT, which is body content about the
+ * originating request.
+ */
+export interface NotificationMetadata {
+  /** The notification kind this content was composed from, e.g. "org.invite". */
+  kind: string;
+  title: string;
+}
+
+/** One notification, said once, for every channel. */
+export interface NotificationContent {
+  metadata: NotificationMetadata;
+  sections: Section[];
+}

package/src/notifications/context.ts

@@ -0,0 +1,70 @@
+/**
+ * Ambient render state — the things a notification's copy depends on but does
+ * not carry (ADR-CONTRACTS-086).
+ *
+ * `RenderContext` exists to remove a hidden `now`. The email layer's
+ * `signature()` read `new Date().getFullYear()` mid-render: the one conceded
+ * impurity in this package, and the reason every render test had to freeze the
+ * clock. Hoisting the year into an explicit context makes the clock read a
+ * single, visible act at the edge — `createRenderContext()` — and leaves
+ * rendering itself a pure function of (content, context).
+ *
+ * The defaults reproduce the values that layer rendered (`COMPANY_NAME` + the
+ * current year), so output is unchanged; what changes is that a caller can now
+ * pin them.
+ *
+ * INVARIANTS:
+ * - Renderers MUST read the brand and the year from here, never from a clock or
+ *   a constant of their own. That is the whole point of the type.
+ * - `createRenderContext()` is the ONLY thing in this domain permitted to read
+ *   the clock, and only to default `copyrightYear`. Pass `copyrightYear` to get
+ *   a fully deterministic context.
+ */
+
+/**
+ * The product name a notification signs off with, absent a caller's own.
+ *
+ * It lives here rather than in the email channel because it is the default for
+ * `Brand.name` — the same answer on every channel — and a channel-agnostic
+ * default sourced from a channel is how the seam ADR-CONTRACTS-086 draws leaks
+ * back. Renderers read `context.brand.name`, never this.
+ */
+export const COMPANY_NAME = "Company Semantics";
+
+/** Who the notification is from, as the recipient sees it. */
+export interface Brand {
+  /** Product name in signatures and footers. */
+  name: string;
+  /** Year in the copyright line. Supplied, never read from a clock at render. */
+  copyrightYear: number;
+}
+
+/** Ambient state every renderer resolves against. */
+export interface RenderContext {
+  brand: Brand;
+}
+
+/** Per-field overrides for `createRenderContext`. */
+export interface RenderContextOverrides {
+  brand?: Partial<Brand>;
+}
+
+/**
+ * Build a `RenderContext`, defaulting to `COMPANY_NAME` and the current year, so
+ * an un-overridden context renders exactly what the email layer rendered before
+ * the year was hoisted out of it.
+ *
+ * This is the one clock read in the domain. Tests and any caller wanting
+ * reproducible bytes should pass `copyrightYear`.
+ */
+export function createRenderContext(
+  overrides?: RenderContextOverrides,
+): RenderContext {
+  return {
+    brand: {
+      name: overrides?.brand?.name ?? COMPANY_NAME,
+      copyrightYear:
+        overrides?.brand?.copyrightYear ?? new Date().getFullYear(),
+    },
+  };
+}

package/src/notifications/definition.ts

@@ -0,0 +1,82 @@
+/**
+ * What one notification kind IS (ADR-CONTRACTS-085).
+ *
+ * A `NotificationDefinition` is the whole of a kind: given its facts and the
+ * ambient state, it says what the notification says. `compose` is the seam —
+ * everything above it is business fact, everything below it is one channel's
+ * opinion about how to draw a sentence.
+ *
+ * This replaced `EmailKindDefinition` (deleted with `src/email/`,
+ * ADR-CONTRACTS-086), and what it DROPS is the point:
+ *
+ * - `subject` is gone. A subject is a title, and a title is content, so it is
+ *   `compose`'s output (`metadata.title`) rather than a registry field. That
+ *   fusion — the headline in `EMAIL_KINDS`, the body in a template function, the
+ *   two interpolated by different code — is what ADR-CONTRACTS-086 set out to
+ *   split. It also retires `renderEmail`'s `resolveSubject`/`subjectData` pair:
+ *   `{orgName}` string substitution against an untyped bag becomes an ordinary
+ *   template literal that the compiler checks.
+ * - `plainTextRequired` / `htmlSupported` are gone, superseded by
+ *   `Renderer.supports`. A kind is not what can or cannot draw an image — that
+ *   is a property of where it is going, and it belongs on the renderer.
+ *
+ * There is deliberately no field naming where a notification may be delivered.
+ * Capability is asked of the renderer, never declared on the kind: tagging a
+ * definition with its destinations puts knowledge of the channel back inside the
+ * thing that exists to be independent of it, and makes every new surface a
+ * rewrite of every definition.
+ *
+ * INVARIANTS:
+ * - `compose` is PURE — a function of `(payload, context)` and nothing else. No
+ *   clock (the year comes from `context.brand`), no environment, no I/O, no
+ *   ambient constant of its own.
+ * - `compose` emits content only. No markup, no styling, no channel names. If a
+ *   value is a formatting choice a channel could reasonably make differently, it
+ *   is the renderer's, not `compose`'s.
+ * - `kind` MUST equal the key this definition sits under in `./registry`.
+ * - Whether PII-bearing elements exist at all is `compose`'s decision, taken from
+ *   what the payload carries — a renderer must never be the thing gating them.
+ */
+
+import type { NotificationContent } from "./content";
+import type { RenderContext, RenderContextOverrides } from "./context";
+import type { NotificationKind } from "./kinds";
+import type { NotificationPayloads } from "./payloads";
+
+/**
+ * One kind's definition, parameterised by the kind so `compose` receives that
+ * kind's payload precisely rather than a union of every payload.
+ *
+ * `NotificationPayloads[K]` is also the structural lock that keeps the two
+ * vocabularies honest: a kind added to `NotificationKind` without facts in
+ * `./payloads` cannot be given a definition, and so cannot reach the registry.
+ *
+ * Members are arrow properties, not method shorthand: the vocabulary-guard reads
+ * method signatures as behaviour smuggled into the vocabulary.
+ */
+export interface NotificationDefinition<
+  K extends NotificationKind = NotificationKind,
+> {
+  /** The kind this defines. MUST match its registry key. */
+  kind: K;
+  /**
+   * The kind's own ambient defaults, layered UNDER a caller's `RenderContext` —
+   * a kind may express a preference, a caller always overrules it.
+   *
+   * The seam exists here rather than on the payload because it is a standing
+   * fact about the kind, not about any one send: a notification a product sends
+   * on a third party's behalf is signed that way every time, and encoding that
+   * on each payload would make every caller responsible for remembering it.
+   *
+   * No kind sets this today. It is the one field kept ahead of a caller, and the
+   * first place to look if this layer starts accreting speculative surface.
+   */
+  defaults?: RenderContextOverrides;
+  /**
+   * Say what this notification says. Pure: `(payload, context)` in, content out.
+   */
+  compose: (
+    payload: NotificationPayloads[K],
+    context: RenderContext,
+  ) => NotificationContent;
+}

package/src/notifications/index.ts

@@ -0,0 +1,104 @@
+/**
+ * Notifications Domain Barrel
+ *
+ * The channel-agnostic notification render layer.
+ * Import from '@company-semantics/contracts/notifications'.
+ *
+ * @see ADR-CONTRACTS-086 for design rationale
+ * @see ADR-CONTRACTS-085 for the definition + registry layer
+ */
+
+// =============================================================================
+// Content — the channel-agnostic semantic model
+// =============================================================================
+
+export type {
+  Body,
+  CallToAction,
+  ChatContinuation,
+  ChatTurn,
+  ChatUnit,
+  ChatUnitItem,
+  Divider,
+  Greeting,
+  HeroImage,
+  KeyValueRow,
+  KeyValueTable,
+  List,
+  MetadataElement,
+  NotificationContent,
+  NotificationElement,
+  NotificationElementType,
+  NotificationMetadata,
+  Notice,
+  Section,
+  Signature,
+  Warning,
+} from "./content";
+
+// =============================================================================
+// Render Context
+// =============================================================================
+
+export type { Brand, RenderContext, RenderContextOverrides } from "./context";
+
+export { createRenderContext } from "./context";
+
+// =============================================================================
+// Renderer
+// =============================================================================
+
+export type { Renderer } from "./renderer";
+
+// =============================================================================
+// Channels — one renderer per channel
+// =============================================================================
+
+export type { RenderedEmail } from "./renderers/email";
+
+export { emailRenderer } from "./renderers/email";
+
+export type {
+  SlackActionsBlock,
+  SlackBlock,
+  SlackButtonElement,
+  SlackContextBlock,
+  SlackDividerBlock,
+  SlackImageBlock,
+  SlackMessage,
+  SlackMrkdwnText,
+  SlackPlainText,
+  SlackSectionBlock,
+} from "./renderers/slack";
+
+export { slackRenderer } from "./renderers/slack";
+
+export { smsRenderer } from "./renderers/sms";
+
+// =============================================================================
+// Kinds — what notifications exist, and the facts each carries
+// =============================================================================
+
+export type { NotificationKind } from "./kinds";
+
+export type { NotificationPayloads } from "./payloads";
+
+// =============================================================================
+// Definition + Registry — what each kind says
+// =============================================================================
+
+export type { NotificationDefinition } from "./definition";
+
+export type { NotificationDefinitions } from "./registry";
+
+export {
+  getNotificationKindDefinition,
+  isValidNotificationKind,
+  NOTIFICATION_DEFINITIONS,
+} from "./registry";
+
+// =============================================================================
+// Render — the entry point
+// =============================================================================
+
+export { renderEmail, renderToChannel } from "./render";

package/src/notifications/kinds/README.md

@@ -0,0 +1,57 @@
+# notifications/kinds/
+
+## Purpose
+
+One module per notification kind (ADR-CONTRACTS-085). Each exports a single
+`NotificationDefinition<K>` whose `compose(payload, context)` says what that
+notification says, as channel-agnostic `NotificationContent`.
+
+These are the ported bodies of the old `src/email/render/*.ts` (deleted,
+ADR-CONTRACTS-086). Each block call became an element node:
+
+| old `email/render/blocks`                           | element                                                           |
+| --------------------------------------------------- | ----------------------------------------------------------------- |
+| `greeting(name?)`                                   | `greeting`                                                        |
+| `paragraph(text)`                                   | `body`                                                            |
+| `keyValue(label, value)` × n (consecutive)          | ONE `keyValueTable` with `n` rows                                 |
+| `security()`                                        | `warning`                                                         |
+| `footer(first, second)`                             | `notice` with two `lines`                                         |
+| `signature()`                                       | `signature`                                                       |
+| `chatUnit(chatUser/chatAssistant/chatDots/chatCta)` | `chatUnit` with `message` / `continuation` / `callToAction` items |
+
+Two things are dropped in the crossing, both because they are a channel's answer
+rather than the notification's: `Spacing` (`"normal"` / `"tight"` / `"none"`),
+and the `Block`'s markup itself.
+
+**Punctuation between a label and its value is dropped with them, and the email
+renderer MUST put it back.** The old `keyValue("Status", "Valid")` rendered
+`Status: Valid`, and `auth-otp`'s `paragraph("Request details:")` a literal
+trailing colon — but `KeyValueRow` owns no separator ("the renderer owns the
+separator and alignment") and `MetadataElement.label` is `"Request details"`, no
+colon, exactly as `../content.ts` documents it. The colon is presentation and
+appears in NO element. A renderer that forgets it drops `:` from every key/value
+row and from the request-details heading.
+
+The registry subject moves the other way — INTO `compose`, as `metadata.title`.
+The old `renderEmail`'s `resolveSubject` / `subjectData` pair has no equivalent
+here: a `{orgName}` placeholder resolved against an untyped bag becomes a
+template literal the compiler checks.
+
+## Invariants
+
+- `compose` is PURE and total: `(payload, context)` in, content out. No clock
+  (`../context` owns the only one), no environment, no I/O.
+- `compose` emits CONTENT — never markup, styling, spacing or a channel name.
+- The brand comes from `context.brand.name`. A definition MUST NOT import
+  `COMPANY_NAME`; that ambient read is what this layer exists to remove.
+- Element ORDER is content. A port must not regroup elements to look tidier —
+  see `security-alert.ts`, which emits two `keyValueTable`s precisely because
+  merging them would move what the recipient reads.
+- Definitions take `formatExpiry`, `titleCase`, `NOTICE` and `ACCESS_PHRASE` from
+  `../text` — never from a renderer. They are content (phrasing and display
+  format), not markup, so they sit beside the kinds rather than inside the
+  channel that used to own them. The output-parity golden asserts these strings
+  byte-for-byte; a second copy of one is the exact failure this migration exists
+  to prevent.
+- A file per kind, named after its old `email/render` counterpart. Kinds do not
+  share a module — the point is that a kind is self-contained.

package/src/notifications/kinds/auth-otp.ts

@@ -0,0 +1,99 @@
+/**
+ * Auth OTP notification (login code).
+ *
+ * INVARIANT: the OTP value is a runtime payload field — never a literal in this
+ * package.
+ *
+ * PRIVACY: request IP / device are PII under GDPR. The old `renderAuthOtp` took
+ * an `includeRequestMetadata` option and the backend passed its env flag. Here the
+ * gate is simply whether the payload carries them: a caller that must not show
+ * request details omits the fields, and `compose` has no third parameter to
+ * disagree with. The decision stays upstream where the policy lives, and the PII
+ * stops being handed to a layer that was told to ignore it.
+ */
+
+import type { KeyValueRow, NotificationElement } from "../content";
+import type { NotificationDefinition } from "../definition";
+
+/** Longest user agent shown before ellipsis, and the slice that leaves room for it. */
+const USER_AGENT_MAX = 80;
+const USER_AGENT_TRUNCATED = 77;
+
+export const authOtpDefinition: NotificationDefinition<"auth.otp"> = {
+  kind: "auth.otp",
+  compose: (payload, context) => {
+    const { otp, expiresInMinutes, requestIp, userAgent } = payload;
+
+    const requestRows: KeyValueRow[] = [
+      ...(requestIp ? [{ label: "IP address", value: requestIp }] : []),
+      ...(userAgent
+        ? [
+            {
+              label: "Device",
+              value:
+                userAgent.length > USER_AGENT_MAX
+                  ? `${userAgent.slice(0, USER_AGENT_TRUNCATED)}...`
+                  : userAgent,
+            },
+          ]
+        : []),
+    ];
+
+    const elements: NotificationElement[] = [
+      { type: "greeting" },
+      { type: "body", text: "A login code was requested." },
+      {
+        type: "chatUnit",
+        items: [
+          {
+            type: "message",
+            role: "assistant",
+            text: "Copy + paste this code in the login form.",
+          },
+          // No href: the code IS the payload, and a renderer must not invent a
+          // destination for it.
+          { type: "callToAction", label: otp },
+        ],
+      },
+      {
+        type: "keyValueTable",
+        rows: [
+          { label: "Status", value: "Valid" },
+          {
+            label: "Expires in",
+            value: `${expiresInMinutes} ${expiresInMinutes === 1 ? "minute" : "minutes"}`,
+          },
+        ],
+      },
+      ...(requestRows.length
+        ? [
+            {
+              // "Request details", not "Request details:" — the email layer's
+              // literal colon is a separator, and separators are the renderer's
+              // (see `../content.ts`, which uses this exact label as its
+              // example). The email renderer must put the colon back.
+              type: "metadata" as const,
+              label: "Request details",
+              rows: requestRows,
+            },
+          ]
+        : []),
+      {
+        type: "notice",
+        lines: [
+          `This login code was sent via ${context.brand.name}.`,
+          "If this wasn't you, no action is required.",
+        ],
+      },
+      { type: "signature" },
+    ];
+
+    return {
+      metadata: {
+        kind: "auth.otp",
+        title: "Your login code for Company Semantics",
+      },
+      sections: [{ elements }],
+    };
+  },
+};