@company-semantics/contracts 34.0.0 → 35.1.0

package/src/notifications/__tests__/definition.test.ts

@@ -0,0 +1,222 @@
+/**
+ * `compose` is where the whole layer's purity claim lives (ADR-CONTRACTS-085):
+ * everything above it is fact, everything below is one channel's opinion. These
+ * tests hold it to the four promises a type cannot express.
+ *
+ * PURITY — the same `(payload, context)` composes the same content, twice, with
+ * the clock moved between. The old `blocks.signature()` read
+ * `new Date().getFullYear()` mid-render, which is why every render test used to
+ * freeze time; the point of `RenderContext` is that these tests do not have to.
+ * Moving the clock and getting identical content is the proof that the ambient
+ * read is really gone.
+ *
+ * THE BRAND SEAM — the ten kinds that footer "sent via Company Semantics" must
+ * read that name from `context.brand.name`, not from an imported constant. A
+ * test that only ever renders the default context cannot tell the difference, so
+ * these override the brand and assert the override lands.
+ *
+ * THE PII GATE — the old `renderAuthOtp` took an `includeRequestMetadata` option
+ * and the backend passed an env flag. `compose` has no such parameter: the gate
+ * is whether the payload carries the fields. That relocation is a
+ * privacy-relevant behaviour change and is pinned here rather than left to the
+ * email wiring to discover.
+ *
+ * CONTENT, NOT MARKUP — the elements carry no HTML. The cheapest possible check
+ * for the mistake this layer exists to prevent.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import type { NotificationContent, NotificationElement } from "../content";
+import { createRenderContext } from "../context";
+import type { NotificationKind } from "../kinds";
+import { NOTIFICATION_DEFINITIONS } from "../registry";
+import { NOTIFICATION_FIXTURES } from "./fixtures";
+
+const CONTEXT = createRenderContext({ brand: { copyrightYear: 2026 } });
+
+/** Compose a kind against its first parity fixture. */
+function compose(
+  kind: NotificationKind,
+  context = CONTEXT,
+): NotificationContent {
+  const fixture = NOTIFICATION_FIXTURES.find((f) => f.kind === kind);
+  if (!fixture) throw new Error(`No parity fixture for kind: ${kind}`);
+  const fn = NOTIFICATION_DEFINITIONS[kind].compose as (
+    p: unknown,
+    c: typeof context,
+  ) => NotificationContent;
+  return fn(fixture.payload, context);
+}
+
+const KINDS = Object.keys(NOTIFICATION_DEFINITIONS) as NotificationKind[];
+
+/** Every element of a composed notification, flattened across its sections. */
+function elementsOf(content: NotificationContent): NotificationElement[] {
+  return content.sections.flatMap((s) => s.elements);
+}
+
+describe("compose purity", () => {
+  it("is deterministic for the same payload and context", () => {
+    for (const kind of KINDS) {
+      expect(compose(kind)).toEqual(compose(kind));
+    }
+  });
+
+  it("does not read the clock", () => {
+    // The impurity this layer retired: the old `blocks.signature()` called
+    // `new Date().getFullYear()` mid-render, so its render tests had to freeze
+    // time to stay stable. These deliberately do not.
+    //
+    // The stub fakes ONLY the argless `new Date()` and `Date.now()` — the clock.
+    // `new Date(iso)` is left alone because parsing a timestamp the PAYLOAD
+    // carries is pure, and two composes rely on it: `formatExpiry` and
+    // security.alert's `Time` row. Faking those too would fail the honest code.
+    const realDate = Date;
+    const before = KINDS.map((kind) => compose(kind));
+    try {
+      globalThis.Date = class extends realDate {
+        constructor(...args: ConstructorParameters<DateConstructor>) {
+          if (args.length === 0) super("2099-01-01T00:00:00.000Z");
+          else super(...args);
+        }
+        static now(): number {
+          return new realDate("2099-01-01T00:00:00.000Z").getTime();
+        }
+      } as DateConstructor;
+
+      expect(KINDS.map((kind) => compose(kind))).toEqual(before);
+    } finally {
+      globalThis.Date = realDate;
+    }
+  });
+
+  it("emits no year — the copyright year is the renderer's, from the context", () => {
+    // The old `signature()` baked the year into its bytes. Here `signature` is a
+    // fieldless element and the year arrives at render time, which is what makes
+    // a composed notification safe to cache, log or compare across a New Year.
+    for (const kind of KINDS) {
+      const signatures = elementsOf(compose(kind)).filter(
+        (e) => e.type === "signature",
+      );
+      expect(signatures).toEqual([{ type: "signature" }]);
+    }
+  });
+});
+
+describe("compose reads ambient state from the context", () => {
+  it("takes the brand name from context.brand, not an imported constant", () => {
+    const context = createRenderContext({
+      brand: { name: "Umbrella Corp", copyrightYear: 2026 },
+    });
+
+    // Ten of the eleven kinds footer "sent via <brand>"; security.alert has no
+    // notice at all, on purpose.
+    const branded = KINDS.filter((kind) => kind !== "security.alert");
+    expect(branded).toHaveLength(10);
+
+    for (const kind of branded) {
+      const notices = elementsOf(compose(kind, context)).filter(
+        (e) => e.type === "notice",
+      );
+
+      expect(notices).toHaveLength(1);
+      expect(notices[0].lines[0]).toContain("Umbrella Corp");
+      expect(notices[0].lines[0]).not.toContain("Company Semantics");
+    }
+  });
+
+  it("still says Company Semantics under an un-overridden context", () => {
+    // The default must reproduce today's bytes, or the parity proof moves.
+    const notice = elementsOf(compose("org.invite")).find(
+      (e) => e.type === "notice",
+    );
+    expect(notice?.lines).toEqual([
+      "This invitation was sent via Company Semantics.",
+      "If you weren't expecting this, no action is required.",
+    ]);
+  });
+});
+
+describe("compose gates PII on the payload, not on an option", () => {
+  const otpCompose = NOTIFICATION_DEFINITIONS["auth.otp"].compose;
+
+  it("omits request details when the payload carries none", () => {
+    const content = otpCompose(
+      { otp: "123456", expiresInMinutes: 10 },
+      CONTEXT,
+    );
+
+    expect(elementsOf(content).map((e) => e.type)).not.toContain("metadata");
+  });
+
+  it("shows request details when the payload carries them", () => {
+    const content = otpCompose(
+      {
+        otp: "246810",
+        expiresInMinutes: 5,
+        requestIp: "203.0.113.4",
+        userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
+      },
+      CONTEXT,
+    );
+
+    const metadata = elementsOf(content).find((e) => e.type === "metadata");
+    expect(metadata).toEqual({
+      type: "metadata",
+      label: "Request details",
+      rows: [
+        { label: "IP address", value: "203.0.113.4" },
+        {
+          label: "Device",
+          value: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
+        },
+      ],
+    });
+  });
+
+  it("truncates an overlong user agent, as the email layer did", () => {
+    const content = otpCompose(
+      { otp: "246810", expiresInMinutes: 5, userAgent: "U".repeat(120) },
+      CONTEXT,
+    );
+
+    const metadata = elementsOf(content).find((e) => e.type === "metadata");
+    expect(metadata).toEqual({
+      type: "metadata",
+      label: "Request details",
+      rows: [{ label: "Device", value: `${"U".repeat(77)}...` }],
+    });
+  });
+
+  it("shows the code itself as a call to action with no href", () => {
+    // `href` absent means the label IS the payload. A renderer must not
+    // fabricate a destination for an OTP.
+    const chatUnit = elementsOf(
+      otpCompose({ otp: "123456", expiresInMinutes: 10 }, CONTEXT),
+    ).find((e) => e.type === "chatUnit");
+
+    expect(chatUnit?.items).toContainEqual({
+      type: "callToAction",
+      label: "123456",
+    });
+  });
+});
+
+describe("compose emits content, not markup", () => {
+  it("puts no HTML in any element of any kind", () => {
+    for (const kind of KINDS) {
+      const serialized = JSON.stringify(compose(kind));
+      expect(serialized).not.toMatch(/<\/?[a-z]+[\s>]/i);
+      expect(serialized).not.toContain("&#39;");
+    }
+  });
+
+  it("carries no spacing — that is a channel's answer, not the notification's", () => {
+    for (const kind of KINDS) {
+      for (const element of elementsOf(compose(kind))) {
+        expect(element).not.toHaveProperty("spacing");
+      }
+    }
+  });
+});

package/src/notifications/__tests__/fixtures.ts

@@ -0,0 +1,226 @@
+/**
+ * The notification fixture corpus: every implemented kind × representative
+ * payload. Shared by `./render-snapshot.test.ts`, `./definition.test.ts`,
+ * `./registry.test.ts` and `../renderers/email/__tests__/render.test.ts`, so a
+ * kind added to the registry is covered everywhere by being added once here.
+ *
+ * WAS `output-parity.golden.ts` (ADR-CONTRACTS-087). These same inputs used to
+ * carry a frozen `OUTPUT_PARITY_GOLDEN` of the `{ subject, text, html }` the
+ * email layer emitted at 32.0.0, asserted byte-for-byte to prove the
+ * multi-channel generalisation (ADR-CONTRACTS-086) changed no output. That proof
+ * passed and shipped in 35.0.0, which discharged it: it was a claim about a
+ * migration, not a freeze on email design. The bytes were retired rather than
+ * rewritten — editing them to match a deliberate redesign would have made the
+ * file assert something false about a layer that no longer exists. They remain
+ * readable in git at `v35.0.0`.
+ *
+ * `./render-snapshot.test.ts` is now the fence: it locks the same fixtures'
+ * rendered output, and unlike the golden it is regenerable on purpose, because
+ * changing how email looks is now an ordinary reviewed diff.
+ *
+ * Capture-time options are not recorded. The old `renderEmail` took a
+ * `RenderEmailOptions`, and one fixture set `includeRequestMetadata: true`; the
+ * entry point has no equivalent because `auth.otp`'s `compose` gates request
+ * details on whether the payload carries them — and that fixture's payload
+ * carries both, so the gate opens anyway.
+ */
+
+import type { NotificationKind } from "../kinds";
+import type { NotificationPayloads } from "../payloads";
+
+/**
+ * The instant every fixture renders under.
+ *
+ * A pinned year, not a frozen clock. The copyright year is a value on
+ * `RenderContext`, so a test states this instant instead of stubbing time —
+ * which is the impurity ADR-CONTRACTS-086 retired. Pinned rather than left to
+ * the wall clock so no snapshot is due to fail on New Year's Day.
+ */
+export const FIXTURE_CLOCK = "2026-07-15T00:00:00.000Z";
+
+/** One case: a kind rendered with a representative payload. */
+export interface NotificationFixture {
+  readonly kind: NotificationKind;
+  /** Variant label, unique within a kind. */
+  readonly name: string;
+  readonly payload: NotificationPayloads[NotificationKind];
+}
+
+/** Stable label for a fixture — also its snapshot key. */
+export function fixtureKey(kind: NotificationKind, name: string): string {
+  return `${kind} · ${name}`;
+}
+
+const fixtures: NotificationFixture[] = [];
+function add<K extends NotificationKind>(
+  kind: K,
+  name: string,
+  payload: NotificationPayloads[K],
+): void {
+  fixtures.push({ kind, name, payload });
+}
+
+const APP = "https://app.companysemantics.ai";
+
+add("auth.otp", "Default", { otp: "123456", expiresInMinutes: 10 });
+add("auth.otp", "Short expiry", { otp: "902413", expiresInMinutes: 1 });
+add("auth.otp", "With request metadata", {
+  otp: "246810",
+  expiresInMinutes: 5,
+  requestIp: "203.0.113.4",
+  userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
+});
+
+add("org.invite", "Admin", {
+  inviterName: "Alex Rivera",
+  orgName: "Acme Corp",
+  role: "admin",
+  acceptUrl: `${APP}/invite/abc123`,
+  expiresAt: "2026-06-13T00:00:00.000Z",
+});
+add("org.invite", "Member", {
+  inviterName: "Alex Rivera",
+  orgName: "Acme Corp",
+  role: "member",
+  acceptUrl: `${APP}/invite/def456`,
+  expiresAt: "2026-06-13T00:00:00.000Z",
+});
+
+add("org.unit_owner_granted", "Unit owner + message", {
+  granterName: "Jordan Lee",
+  recipientName: "Sam Chen",
+  orgName: "Acme Corp",
+  unitName: "Platform Engineering",
+  roleLabel: "Unit owner",
+  ctaUrl: `${APP}/org/unit/42`,
+  message: "Welcome aboard — glad to have you owning this team.",
+});
+add("org.unit_owner_granted", "Delegate with expiry", {
+  granterName: "Jordan Lee",
+  orgName: "Acme Corp",
+  unitName: "Platform Engineering",
+  roleLabel: "Delegate",
+  ctaUrl: `${APP}/org/unit/42`,
+  expiresAt: "2026-06-13T00:00:00.000Z",
+});
+
+add("org.ownership_transfer", "With note + from", {
+  orgName: "Acme Corp",
+  acceptUrl: `${APP}/owner-transfer/accept/tok123`,
+  expiresAt: "2026-06-13T00:00:00.000Z",
+  note: "Handing this over as I move to an advisory role.",
+  fromName: "Jordan Lee",
+});
+add("org.ownership_transfer", "No note (admin)", {
+  orgName: "Acme Corp",
+  acceptUrl: `${APP}/owner-transfer/accept/tok456`,
+  expiresAt: "2026-06-13T00:00:00.000Z",
+});
+
+add("org.ownership_transfer_completed", "Default", {
+  orgName: "Acme Corp",
+  newOwnerEmail: "new.owner@acme.com",
+});
+
+add("security.alert", "Excessive OTP requests", {
+  alertType: "excessive_otp_requests",
+  details: "12 login codes requested in 5 minutes",
+  timestamp: "2026-07-12T14:30:00Z",
+});
+add("security.alert", "Unusual login location", {
+  alertType: "unusual_login_location",
+  details: "Login from Berlin, DE",
+  timestamp: "2026-07-12T14:30:00Z",
+});
+
+const CHAT_BASE = {
+  sharedByName: "Alex Rivera",
+  visibility: "private",
+} as const;
+add("chat.shared", "Default", {
+  ...CHAT_BASE,
+  chatTitle: "API design discussion",
+  shareUrl: `${APP}/share/abc123`,
+  previewText:
+    "Here are my thoughts on the REST API design for the new authentication endpoints.",
+});
+add("chat.shared", "No preview", {
+  ...CHAT_BASE,
+  chatTitle: "Quick sync notes",
+  shareUrl: `${APP}/share/xyz789`,
+});
+add("chat.shared", "Long title", {
+  ...CHAT_BASE,
+  visibility: "public",
+  chatTitle:
+    "This is a very long chat title that should be truncated to fit the layout properly",
+  shareUrl: `${APP}/share/long456`,
+  previewText: "The assistant response preview text.",
+});
+add("chat.shared", "Long preview", {
+  ...CHAT_BASE,
+  chatTitle: "Code review feedback",
+  shareUrl: `${APP}/share/preview789`,
+  previewText:
+    "I reviewed the pull request and found several areas that need improvement. The authentication logic needs better error handling, and the database queries could be optimized.",
+});
+add("chat.shared", "Short", {
+  ...CHAT_BASE,
+  chatTitle: "Hi",
+  shareUrl: `${APP}/share/short123`,
+  previewText: "Hello!",
+});
+
+add("share.granted", "Document · editor · message", {
+  granterName: "Jordan Lee",
+  recipientName: "Sam Chen",
+  entityLabel: "document",
+  entityTitle: "Q3 Roadmap",
+  accessLevel: "editor",
+  ctaUrl: `${APP}/doc/roadmap`,
+  message: "Take a look before Thursday's planning.",
+});
+add("share.granted", "Meeting · viewer · no title", {
+  granterName: "Jordan Lee",
+  entityLabel: "meeting",
+  accessLevel: "viewer",
+  ctaUrl: `${APP}/meeting/8842`,
+});
+
+add("companyMd.access_requested", "With message", {
+  requesterName: "Sam Chen",
+  docTitle: "Engineering Handbook",
+  message: "I'd like to contribute the onboarding section.",
+  reviewUrl: `${APP}/doc/handbook?request=req_123`,
+});
+add("companyMd.access_requested", "No message", {
+  requesterName: "Sam Chen",
+  docTitle: "Engineering Handbook",
+  reviewUrl: `${APP}/doc/handbook?request=req_456`,
+});
+
+add("companyMd.access_request_approved", "Editor", {
+  approverName: "Jordan Lee",
+  docTitle: "Engineering Handbook",
+  accessLevel: "editor",
+  docUrl: `${APP}/doc/handbook`,
+});
+add("companyMd.access_request_approved", "Viewer", {
+  approverName: "Jordan Lee",
+  docTitle: "Engineering Handbook",
+  accessLevel: "viewer",
+  docUrl: `${APP}/doc/handbook`,
+});
+
+add("companyMd.access_request_denied", "With reason", {
+  approverName: "Jordan Lee",
+  docTitle: "Engineering Handbook",
+  reason: "This doc is limited to the platform team for now.",
+});
+add("companyMd.access_request_denied", "No reason", {
+  approverName: "Jordan Lee",
+  docTitle: "Engineering Handbook",
+});
+
+/** The corpus — every implemented kind × representative variants. */
+export const NOTIFICATION_FIXTURES: readonly NotificationFixture[] = fixtures;

package/src/notifications/__tests__/kinds.test.ts

@@ -0,0 +1,80 @@
+/**
+ * `NotificationKind` is the migration's central claim: that the eleven things
+ * the email layer could actually SAY are notifications, not emails
+ * (ADR-CONTRACTS-085).
+ *
+ * WHAT THESE TESTS USED TO DO, AND WHY THEY NO LONGER DO IT. Membership was
+ * asserted against `IMPLEMENTED_EMAIL_KINDS`, and the union's deliberate
+ * divergence against `EmailKind` — one live union checked against another. Both
+ * sides of both comparisons were `src/email/`'s, and that directory is now
+ * deleted (ADR-CONTRACTS-086). Those assertions were not rewired, because there
+ * is nothing to rewire them to: an assertion with one side left is not a weaker
+ * version of itself, it is a tautology that reads like coverage. They were
+ * removed rather than allowed to pass vacuously.
+ *
+ * What still holds the membership claim, in the order it bites:
+ * - the `Record<NotificationKind, true>` below, which fails to COMPILE if a
+ *   union member is added without being named here;
+ * - the frozen list in the first test, which fails at runtime if one is removed;
+ * - `./registry.test.ts`, which pins a definition for every member;
+ * - `./render-snapshot.test.ts`, which pins rendered output for every member.
+ *   That is what carries "these are exactly the kinds email can render".
+ *
+ * The DIVERGENCE is the easiest thing in this change to mistake for an omission,
+ * so it keeps a test of its own. `auth.magic_link` was a registered subject with
+ * no template: the old `renderEmail` accepted it and threw. Excluding it is what
+ * makes the notification registry total, so its absence is asserted on purpose —
+ * restoring it "for symmetry" would put the runtime hole back.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import type { NotificationKind } from "../kinds";
+
+/**
+ * Every notification kind, exhaustively. The `Record` type documents the lock; a
+ * new union member must be named here. The assertions below are what enforce it
+ * at runtime — `src/tsconfig.json` excludes test files, so the type alone would
+ * not fail a build.
+ */
+const ALL_NOTIFICATION_KINDS: Record<NotificationKind, true> = {
+  "auth.otp": true,
+  "org.invite": true,
+  "org.unit_owner_granted": true,
+  "org.ownership_transfer": true,
+  "org.ownership_transfer_completed": true,
+  "security.alert": true,
+  "chat.shared": true,
+  "share.granted": true,
+  "companyMd.access_requested": true,
+  "companyMd.access_request_approved": true,
+  "companyMd.access_request_denied": true,
+};
+
+const KINDS = Object.keys(ALL_NOTIFICATION_KINDS).sort();
+
+describe("NotificationKind", () => {
+  it("has exactly the eleven kinds with something to say", () => {
+    expect(KINDS).toEqual([
+      "auth.otp",
+      "chat.shared",
+      "companyMd.access_request_approved",
+      "companyMd.access_request_denied",
+      "companyMd.access_requested",
+      "org.invite",
+      "org.ownership_transfer",
+      "org.ownership_transfer_completed",
+      "org.unit_owner_granted",
+      "security.alert",
+      "share.granted",
+    ]);
+  });
+
+  it("excludes auth.magic_link, the one kind email registered without implementing", () => {
+    // Deliberate, not an oversight: `renderEmail("auth.magic_link", …)`
+    // type-checked and threw. A kind earns membership by having something to
+    // say, not by having a subject reserved for it. `./registry.test.ts` asserts
+    // `isValidNotificationKind` rejects it at the runtime boundary too.
+    expect(KINDS).not.toContain("auth.magic_link");
+  });
+});