feat(teams): phase 8 — the notifications bridge, and the gate §7.2 could not check

The same Team event as §6, delivered a third time: push, email, and now a
Discord channel the operator configured. Not a second pipeline — teamNotify.js
already computed the recipient set once, so the bridge is a sink beside the two
that were there.

The design's gate has no data source. §7.2 bridges an event only if "its
visibility is public, or its destination channel is configured for a
members-only Team context". The four team.* streams carry no visibility; forum
threads have no public/members column because a forum is members-only by
construction; and core cannot see a Discord channel's permissions. So §7.2's own
example config names exactly the two events that are never public.

The gate is therefore an attributed operator acknowledgement, in the shape
teams_forum_uploads_ack already uses. It is a precondition — 422, not a quiet
drop at delivery — it is re-asked at delivery as well as at the save, and
changing the channel clears it, because an acknowledgement is about a
destination and cannot survive the destination changing underneath it.

The design's DDL cannot hold its own default row: MariaDB coerces every PRIMARY
KEY column to NOT NULL, so `team_id NULL` — the deployment-wide default every
override overrides — is unrepresentable. Proved on a real MariaDB (error 1048).
Replaced with a surrogate id, a generated team_key AS IFNULL(team_id, 0) in the
unique key, and the foreign key the original had no room for.

One-shot, not queued: "identical to announce and mod-reverse" names two
different reliability models, and a Team notification is the moment it
describes.

Co-Authored-By: Claude <noreply@anthropic.com>

bot/src/discord/teamNotify.js

@@ -0,0 +1,80 @@
+// Team notifications posted into an operator-configured channel (TEAMS.md §7.2).
+//
+// **The channel comes from the app, not from guild_config.** `newsAnnounce` looks
+// its channel up here because there is exactly one #news; a Team's destination is
+// per-Team configuration living in `team_integration_config`, and a bot that
+// resolved it would need a second copy of that table and a second place for it to
+// drift. The app sends the id it already decided on.
+//
+// **Everything this file knows about a Team it was told.** No lookups, no
+// membership checks, no access decisions: whether this content may reach this
+// channel was settled on the site, where the acknowledgement that gates it lives.
+// The bot is the transport, exactly as it is for slash commands.
+const { EmbedBuilder } = require('discord.js')
+
+const brand = require('../brand')
+const createLogger = require('../utils/logger')
+
+const log = createLogger('team-notify')
+
+// Discord's own limits. Truncating here rather than trusting the app is not
+// distrust — an embed that exceeds them is rejected wholesale, and a message
+// silently not appearing is the worst failure mode this path has.
+const TITLE_MAX = 256
+const DESCRIPTION_MAX = 4096
+
+const clamp = (value, max) => {
+  const text = String(value || '').trim()
+  if (!text) return null
+  return text.length > max ? `${text.slice(0, max - 1)}…` : text
+}
+
+// What each stream is called in a channel. The app composes the BODY; this is
+// only the label above it, and it is here because it is Discord presentation —
+// the same reason the embed colour is.
+const HEADINGS = {
+  'team.member.joined': 'New member',
+  'team.leadership.changed': 'Leadership change',
+  'team.forum.post': 'New forum post',
+  'team.announcement': 'Announcement',
+}
+
+async function postTeamNotification(client, { channelId, stream, teamName, teamUrl, title, body, url }) {
+  if (!channelId) throw new Error('No channel id supplied.')
+
+  const channel = await client.channels.fetch(channelId).catch(() => null)
+  if (!channel || !channel.isTextBased()) {
+    throw new Error('Configured channel is missing, not text-based, or not visible to the bot.')
+  }
+
+  const heading = HEADINGS[stream] || 'Team update'
+  const name = clamp(teamName, 120) || 'A team'
+
+  const embed = new EmbedBuilder()
+    .setColor(brand.accentInt)
+    // The Team is the AUTHOR line and the event is the title, not the other way
+    // round: a channel carrying one Team's events would otherwise repeat its name
+    // as every heading, and a channel carrying several needs the name to be the
+    // thing the eye lands on first.
+    .setAuthor(teamUrl ? { name, url: teamUrl } : { name })
+    .setTitle(clamp(title, TITLE_MAX) || heading)
+
+  if (url) embed.setURL(url)
+
+  // Both a title and a body means a forum post: the heading has to go somewhere
+  // or "New forum post" and "Announcement" become indistinguishable once the
+  // thread title takes the title slot.
+  //
+  // **Clamped AFTER the heading is prepended, not before.** Clamping the body and
+  // then adding a prefix produces a description one heading longer than the limit,
+  // which discord.js rejects outright — so an over-long post would not arrive at
+  // all rather than arriving truncated. The prefix is part of what has to fit.
+  const composed = title && body ? `**${heading}**\n${String(body)}` : body
+  const description = clamp(composed, DESCRIPTION_MAX)
+  if (description) embed.setDescription(description)
+
+  await channel.send({ embeds: [embed] })
+  log.info('team notification posted', { stream, channelId, team: name })
+}
+
+module.exports = { postTeamNotification, HEADINGS, clamp, TITLE_MAX, DESCRIPTION_MAX }

bot/src/internal/internal.controller.js

@@ -1,5 +1,6 @@
 const discordManager = require('../discord/discordManager')
 const newsAnnounce = require('../discord/newsAnnounce')
+const teamNotify = require('../discord/teamNotify')
 const modLog = require('../discord/modLog')
 const createLogger = require('../utils/logger')
 
@@ -121,4 +122,42 @@ async function refreshCommands(req, res) {
   }
 }
 
-module.exports = { setConfig, getStatus: getStatusHandler, announce, reverseModAction, refreshCommands }
+// POST /internal/team-notify — a Team notification the site has already decided
+// belongs in a channel (TEAMS.md §7.2). Body: { channel_id, stream, team_name,
+// team_url, title, body, url }.
+//
+// **The site chose the channel and the site checked the access.** Whether
+// members-only forum text may reach this channel is an acknowledgement recorded
+// against team_integration_config, and re-deciding it here would mean the bot
+// holding a copy of a policy it cannot see the inputs to.
+//
+// 503 when disconnected and 400 for a channel the bot cannot post to, matching
+// /internal/announce — the caller is one-shot and best-effort and only logs the
+// difference, but an operator debugging a silent channel needs the two to read
+// differently in the bot's log.
+async function teamNotifyHandler(req, res) {
+  const connection = discordManager.getConnection()
+  if (!connection) return res.status(503).json({ message: 'Bot is not connected' })
+
+  const { channel_id: channelId, stream, team_name: teamName, team_url: teamUrl, title, body, url } = req.body || {}
+  if (!channelId || !stream) {
+    return res.status(400).json({ message: 'channel_id and stream are required' })
+  }
+
+  try {
+    await teamNotify.postTeamNotification(connection.client, { channelId, stream, teamName, teamUrl, title, body, url })
+    return res.json({ posted: true })
+  } catch (err) {
+    log.warn('team-notify failed', { message: err.message, stream, channelId })
+    return res.status(400).json({ message: err.message })
+  }
+}
+
+module.exports = {
+  setConfig,
+  getStatus: getStatusHandler,
+  announce,
+  reverseModAction,
+  refreshCommands,
+  teamNotify: teamNotifyHandler,
+}

bot/src/internal/internal.routes.js

@@ -12,5 +12,6 @@ router.get('/status', ctrl.getStatus)
 router.post('/announce', ctrl.announce)
 router.post('/mod-reverse', ctrl.reverseModAction)
 router.post('/refresh-commands', ctrl.refreshCommands)
+router.post('/team-notify', ctrl.teamNotify)
 
 module.exports = router

bot/test/teamNotify.test.js

@@ -0,0 +1,138 @@
+// ── The bot's half of the Team notifications bridge (TEAMS.md §7.2) ────────
+//
+// Nothing here talks to Discord. `channel` is a fake that records what was sent,
+// and the assertions are about the three things this side genuinely owns:
+//
+//   1. **the channel comes from the app and is never looked up.** `newsAnnounce`
+//      reads guild_config because there is one #news; a Team's destination is
+//      per-Team configuration, and a bot that resolved it would hold a second
+//      copy of a table it cannot see the inputs to;
+//   2. **a channel the bot cannot post to fails loudly rather than silently.** A
+//      caller that is one-shot and best-effort only logs the difference, but an
+//      operator debugging a quiet channel needs the bot's log to distinguish
+//      "not connected" from "that id is not a text channel";
+//   3. **Discord's own limits are enforced here.** An embed that exceeds them is
+//      rejected WHOLESALE, so a long forum body must be truncated on this side
+//      even though the app already excerpted it — the app's limit is a product
+//      decision and this one is a protocol constraint.
+
+const { test } = require('node:test')
+const assert = require('node:assert/strict')
+
+const teamNotify = require('../src/discord/teamNotify')
+
+// A fake channel that records what it was sent. `isTextBased` is the one method
+// the code branches on, so it is the one worth making configurable.
+function fakeChannel({ textBased = true } = {}) {
+  const sends = []
+  return {
+    sends,
+    isTextBased: () => textBased,
+    send: async (payload) => { sends.push(payload); return { id: 'm1' } },
+  }
+}
+
+function fakeClient(channel, { throws = false } = {}) {
+  return {
+    channels: {
+      fetch: async (id) => {
+        if (throws) throw new Error('Unknown Channel')
+        return id === 'chan-1' ? channel : null
+      },
+    },
+  }
+}
+
+const post = (client, over = {}) => teamNotify.postTeamNotification(client, {
+  channelId: 'chan-1',
+  stream: 'team.forum.post',
+  teamName: 'Blackthorn’s Legion',
+  teamUrl: 'https://site/guilds/blackthorns-legion',
+  title: 'Siege tonight',
+  body: 'Meet at the moongate.',
+  url: 'https://site/guilds/blackthorns-legion?thread=41',
+  ...over,
+})
+
+// ── 1. The channel is the app's decision ───────────────────────────────────
+
+test('the message goes to the channel the app named', async () => {
+  const channel = fakeChannel()
+  await post(fakeClient(channel))
+  assert.equal(channel.sends.length, 1)
+  const [embed] = channel.sends[0].embeds
+  assert.equal(embed.data.title, 'Siege tonight')
+  assert.equal(embed.data.author.name, 'Blackthorn’s Legion')
+  assert.equal(embed.data.url, 'https://site/guilds/blackthorns-legion?thread=41')
+})
+
+test('no channel id at all is refused before anything is fetched', async () => {
+  await assert.rejects(() => post(fakeClient(fakeChannel()), { channelId: '' }), /No channel id/)
+})
+
+// ── 2. A channel the bot cannot use ────────────────────────────────────────
+
+test('a channel the bot cannot see is a clear error, not a silent no-op', async () => {
+  await assert.rejects(() => post(fakeClient(null)), /missing, not text-based, or not visible/)
+})
+
+test('a fetch that throws is reported the same way — the bot does not distinguish gone from hidden', async () => {
+  await assert.rejects(() => post(fakeClient(fakeChannel(), { throws: true })), /missing, not text-based/)
+})
+
+test('a voice channel is refused', async () => {
+  await assert.rejects(() => post(fakeClient(fakeChannel({ textBased: false }))), /not text-based/)
+})
+
+// ── 3. Discord's limits, and the heading ───────────────────────────────────
+
+test('an over-long title is truncated rather than rejected by Discord as a whole', async () => {
+  const channel = fakeChannel()
+  await post(fakeClient(channel), { title: 'y'.repeat(400) })
+  const [embed] = channel.sends[0].embeds
+  assert.equal(embed.data.title.length, teamNotify.TITLE_MAX)
+  assert.ok(embed.data.title.endsWith('…'))
+})
+
+test('an over-long body is truncated to the description limit', async () => {
+  const channel = fakeChannel()
+  await post(fakeClient(channel), { body: 'z'.repeat(9000) })
+  const [embed] = channel.sends[0].embeds
+  assert.ok(embed.data.description.length <= teamNotify.DESCRIPTION_MAX + 32)
+})
+
+test('a titled event keeps its heading, so a post and an announcement stay distinguishable', async () => {
+  const channel = fakeChannel()
+  await post(fakeClient(channel), { stream: 'team.announcement' })
+  const [embed] = channel.sends[0].embeds
+  assert.match(embed.data.description, /^\*\*Announcement\*\*/)
+  assert.match(embed.data.description, /Meet at the moongate\./)
+})
+
+test('a roster event has no title, so the heading becomes the title', async () => {
+  const channel = fakeChannel()
+  await post(fakeClient(channel), { stream: 'team.member.joined', title: null, body: '3 new members joined.' })
+  const [embed] = channel.sends[0].embeds
+  assert.equal(embed.data.title, 'New member')
+  assert.equal(embed.data.description, '3 new members joined.', 'no heading prefix when the title already is one')
+})
+
+test('an unknown stream still posts, under a neutral heading', async () => {
+  const channel = fakeChannel()
+  await post(fakeClient(channel), { stream: 'team.something.new', title: null })
+  const [embed] = channel.sends[0].embeds
+  assert.equal(embed.data.title, 'Team update')
+})
+
+test('a missing team name does not produce an embed with an empty author line', async () => {
+  const channel = fakeChannel()
+  await post(fakeClient(channel), { teamName: '', teamUrl: null })
+  const [embed] = channel.sends[0].embeds
+  assert.equal(embed.data.author.name, 'A team')
+  assert.equal(embed.data.author.url, undefined)
+})
+
+test('clamp treats whitespace-only as absent, which is what keeps an empty description off the embed', async () => {
+  assert.equal(teamNotify.clamp('   ', 100), null)
+  assert.equal(teamNotify.clamp('ok', 100), 'ok')
+})