pi-roundtable 0.30.3 → 0.31.0

package/CHANGELOG.md

@@ -5,6 +5,21 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.31.0] - 2026-11-01
+
+### Added
+
+- `DiscordCard.preview`: one line of plain text that makes a card a legacy message instead of a Components V2 one, so a card's push and desktop notification is no longer blank. The preview (whitespace flattened, at most 2,000 characters) is the message's `content`, the card is one embed (title, sections as the description, `accent` as the colour, `footer`, `thumbnail`, `image`) and `buttons`, `links` and `selects` are ordinary action rows. It works through `sayCard`, `postCard`, `editCard`, `editWebhookCard` and a forum post's first message; an edit sets `content` too. A card without `preview` is unchanged. The poster cannot change a message's kind: an edit that would turn a Components V2 message into a preview card, or the other way round, is `rejected`. A preview card's embed text is at most 4,096 characters once the sections are joined, its footer 2,048 and the embed 6,000 in all, else `invalid`.
+- `DiscordPoster.createForumPost(forumId, { name, card | content, appliedTags?, autoArchive?, mentions? })` returns `{ threadId, messageId }` (`ForumPost`, `ForumPostCreated`, `ThreadAutoArchive`); the first message of a post has the thread's own id, so `editCard(threadId, messageId, card)` edits a card first message. `DiscordPoster.forumTags(forumId)` and `setForumTags(forumId, tags)` read and replace a forum's tags (`ForumTag`, `ForumTagInput`; a tag sent with its id is kept), and `setPostTags(threadId, tagIds)` replaces a post's tags. `renameChannel` is documented to rename a thread or a forum post too.
+- `DiscordPoster.channelKind(channelId)` returns `{ guildId, kind, parentId? }` (`ChannelKindInfo`) with `kind` one of `text`, `category`, `thread`, `forum`, `forum_post` and `other` (`ChannelKind`). `DiscordReason` has a new `not_forum`, for a forum call on a channel that is no forum and `setPostTags` on a thread that is no forum post.
+- Archived forum posts: Discord refuses a rename, a retag and any message edit in an archived thread (400, code 50083), so `setPostTags` and `renameChannel` of a thread send `archived: false` in the same request, and `editCard` on a post's first message (`messageId` equal to `threadId`) opens an archived post and sends the edit again. `editCard` on another message of an archived thread stays `rejected`; call `setThreadArchived(threadId, false)` first. A locked post is `forbidden` without Manage Threads. `channelKind` no longer keeps the category of a text channel or forum (a thread's parent it still keeps), and `say`, `sayCard` and a webhook `post` into a forum's own id are `rejected` (use `createForumPost`). The fake and the emulator behave the same way.
+- `InboundMessage.thread?: { parentId, parentKind }`, set by the Discord surface for a message written in a thread: `parentKind` is `text`, `forum` or `other`, so a claim answers a mention in a forum post in place instead of starting a thread.
+- `fakeDiscordPoster` keeps the same calls: `forums` (a forum's tags, `FakeForum`), forum posts as channels with `appliedTags`, `channelKind`, and preview cards held with the preview as the message content. The poster contract scenarios cover all of it for the fake and the real poster over the emulated Discord, which now also emulates forums, forum posts, tags and legacy messages with embeds.
+
+## [0.30.4] - 2026-11-01
+
+- Release for the web package's changes (see its changelog); no core behavior changes.
+
 ## [0.30.3] - 2026-11-01
 
 - 0.30.2 was tagged but never published: its release run stopped on lint (a hook's dependency suppression the change had dropped) before any package was published. 0.30.3 carries 0.30.2's changes. No core behavior changes.

package/docs/plugins.md

@@ -2905,15 +2905,16 @@ await poster.edit(channelId, posted.messageId, { content: "Hello again" }, ["rel
 await poster.remove(channelId, posted.messageId, ["relay"]);
 ```
 
-What it covers: webhook posts under names you choose (`post`, `edit`, `remove`, `webhookIds`, `setAvatar`, `onWebhookMade`), cards posted through such a webhook (`postCard`, `editWebhookCard`), the bot's own messages and cards (`say`, `sayCard`, `editCard`, `deleteAsBot`), direct messages (`sendDirect`), pins, reading (`message`, `recentMessages`, `botUserId`, `channelGuild`, `canView`, `memberName`), text channels (`createTextChannel`, `textChannels`, `deleteChannel`, `renameChannel`) and threads (`startThread`, `setThreadArchived`, `threadState`, `threadCloser`).
+What it covers: webhook posts under names you choose (`post`, `edit`, `remove`, `webhookIds`, `setAvatar`, `onWebhookMade`), cards posted through such a webhook (`postCard`, `editWebhookCard`), the bot's own messages and cards (`say`, `sayCard`, `editCard`, `deleteAsBot`), direct messages (`sendDirect`), pins, reading (`message`, `recentMessages`, `botUserId`, `channelGuild`, `canView`, `memberName`), text channels (`createTextChannel`, `textChannels`, `deleteChannel`, `renameChannel`, `channelKind`), threads (`startThread`, `setThreadArchived`, `threadState`, `threadCloser`) and forums (`forumTags`, `setForumTags`, `createForumPost`, `setPostTags`).
 Use `DISCORD.connection.channelInfo(channelId)` to read what a channel is called now: it comes from the gateway's cache.
 
 The rules the poster keeps, so a plugin does not rediscover them:
 
 - **Webhooks are named by the plugin.** `post` finds the bot's webhook of that name in the channel, or makes it on first use; a same-named webhook someone else made is never used. A plugin that needs several voices keeps one name per voice, so the `webhookId` on a message tells them apart. A webhook name, and a post's `username`, are 1 to 80 characters without "discord" or "clyde" in any case (full-width letters too); a username is not "everyone" or "here" either. Anything else is refused as `invalid` before a request is sent. `edit` and `remove` take the names to ask, in order, since a webhook changes only its own messages; they make no webhook. `remove` falls back to deleting as the bot (Manage Messages) for a message an earlier webhook of the same name posted.
 - **Nothing pings by accident.** Every post, edit, card and direct message sends `allowed_mentions` with `parse: []` and, for a post, the `mentions` users you list (at most 20). `@everyone`, roles and users merely named in the text never ping.
-- **Cards are Components V2 messages.** A card carries no `content`. Three lessons: every `editCard` re-sends the Components V2 flag (without it Discord answers a 400); a message posted by `say` cannot be edited into a card (`rejected`: delete it and post a card, which changes the message id); and a pin makes Discord post a system notice (type 6) as the bot, which `recentMessages` lists, `deleteAsBot` deletes, and nothing can edit (`rejected`, Discord's 50021), so skip it when looking for your own message.
+- **Cards are Components V2 messages.** A card carries no `content`, so a card alone makes a blank push or desktop notification; give it a `preview` (next bullet) when that matters. Three lessons: every `editCard` re-sends the Components V2 flag (without it Discord answers a 400); a message posted by `say` cannot be edited into a card (`rejected`: delete it and post a card, which changes the message id); and a pin makes Discord post a system notice (type 6) as the bot, which `recentMessages` lists, `deleteAsBot` deletes, and nothing can edit (`rejected`, Discord's 50021), so skip it when looking for your own message.
 - **A card can carry a picture.** `thumbnail: { url, description? }` makes the heading a Section with a small picture beside it; `image: { url, description? }` puts a Media Gallery of one picture under the text sections and above the quiet last line. Both take an `https` address of at most 2,048 characters and an alt text of 1 to 1,024 characters, else `invalid`; `editCard` and `editWebhookCard` keep them when you send them again, and a card without them is sent exactly as before. Discord fetches the address itself, so it must be reachable from the internet.
+- **A card can carry a preview line for the notification.** `DiscordCard.preview` is one line of plain text (whitespace runs, line breaks included, become one space; at most 2,000 characters after that, and about 120 reads best). Discord builds a push or desktop notification from a message's `content`, which a Components V2 message cannot have, so a card with a `preview` is sent as a legacy message instead: `content` is the preview, one embed holds the card (the title; the sections joined by blank lines as the description; `accent` as the colour; `footer`; `thumbnail` and `image` as the embed's, which have no alt text, so a `description` is dropped) and `buttons`, `links` and `selects` are ordinary action rows, no Components V2 flag. It works for `sayCard`, `postCard`, `editCard`, `editWebhookCard` and a forum post's first message alike, and an edit sets `content` too. The same text guard holds (3,800 characters in all), a title is at most 256 characters, the embed's text (the sections joined by blank lines) at most 4,096, its footer at most 2,048 and the title, text and footer together at most 6,000, and a card has at most five rows (one for each menu and one for the buttons), else `invalid`. A card without `preview` is sent exactly as before. The poster cannot change a message's kind: an edit that would turn a Components V2 message into a preview card, or a preview card into Components V2, is `rejected` (delete it and post a new one, which changes the message id), so decide once per message. An edit that leaves out the buttons removes them.
 - **A webhook can post a card.** `postCard` takes the same `webhook`, `username` and `avatarUrl` as `post` plus a `card`, and sends it with `with_components=true`, which Discord allows for the bot's own (application-owned) webhooks; a button or menu on it reaches your interaction handler like one on a bot card, and the colour bar stays. `editWebhookCard(channelId, messageId, card, webhooks)` asks each named webhook in order, as `edit` does: `message_gone` when none posted it, `rejected` for a message that is not a card. The webhook's token is never logged or put in an error.
 
 ```ts
@@ -2932,11 +2933,14 @@ await poster.postCard(channelId, {
 });
 ```
 
-- **A channel is renamed twice in ten minutes.** Discord answers a third with a wait of minutes. `renameChannel` does not queue it: after ten seconds it fails as `unavailable`, and the held request is aborted, never sent later.
+- **A channel is renamed twice in ten minutes.** Discord answers a third with a wait of minutes. `renameChannel` does not queue it: after ten seconds it fails as `unavailable`, and the held request is aborted, never sent later. A thread, a forum post included, is a channel, so `renameChannel(threadId, name)` renames it the same way (Manage Threads for a post someone else made), under the same limit per thread; it opens an archived thread again, as Discord would refuse the rename otherwise.
+- **`channelKind` says what a channel is.** `channelKind(channelId)` returns `{ guildId, kind, parentId? }` with `kind` one of `text`, `category`, `thread`, `forum`, `forum_post` or `other` (voice, stage, announcement, media). A thread whose parent is a forum is a `forum_post`, a thread of any other channel a `thread`; `parentId` is the thread's parent (the forum for a post) or a channel's category. It keeps a channel's guild and type and a thread's parent after the first read; the category of any other channel can change when someone moves it, so `channelKind` reads it afresh each time. A direct-message channel is `invalid` with `wrong_guild`. A plugin that answers a mention by starting a thread asks it first, or reads `InboundMessage.thread`: a mention inside a thread or a forum post is answered in place, and `startThread` fails there.
+- **Forums.** `forumTags(forumId)` lists a forum's tags (`{ id, name, moderated, emoji? | emojiId? }`). `setForumTags(forumId, tags)` replaces the whole set (Manage Channels), because Discord only takes it whole: a tag sent with its `id` is kept and may be renamed, one without is made, one left out is deleted, so add a tag with `setForumTags(id, [...(await forumTags(id)), { name: "new" }])`. A forum holds at most 20 tags, a name 1 to 20 characters, a tag has a Unicode `emoji` or a custom `emojiId`, not both. A forum call on a channel that is no forum is `invalid` with `not_forum`. Making a forum channel is not in the poster.
+- **Forum posts.** `createForumPost(forumId, { name, card | content, appliedTags?, autoArchive?, mentions? })` returns `{ threadId, messageId }`. Discord takes a post and its first message in one request, so the first message is part of the call: a card (Components V2, or a preview card) or plain text (`mentions` names the users it may ping, as `say`'s). A post's first message has the thread's own id, so `messageId` equals `threadId`; `editCard(threadId, messageId, card)` edits a card first message, `pin`, `say` and `sayCard` take the thread id as a channel's. `appliedTags` is at most five ids the forum offers (a tag it does not offer is `rejected`); `autoArchive` is 60, 1,440, 4,320 or 10,080 minutes, a week by default. `setPostTags(threadId, tagIds)` replaces a post's tags (none clears them); a thread that is not a forum post is `invalid` with `not_forum`. `forbidden` without Create Posts. A forum takes posts, not messages: `say`, `sayCard` and a webhook `post` into the forum's own id are `rejected`. **An archived post.** A post nobody writes in archives itself (a week by default), and Discord refuses every edit of an archived thread (400, code 50083). `setPostTags` and `renameChannel` therefore send `archived: false` in the same request, which opens the post again; `editCard(threadId, threadId, card)` on a post's first message opens an archived post and sends the edit again. `editCard` on any other message of an archived thread is `rejected`: call `setThreadArchived(threadId, false)` first (`say` and `sayCard` already wake an archived thread). A locked post stays `forbidden` without Manage Threads. Scheduled events and moving channels between categories are not in the poster.
 - **Threads.** `startThread` makes a public thread on a message that archives itself after a week and wakes on the next post. The bot needs no Manage Threads to archive or open a thread it started; a locked thread needs it to open again (`forbidden`). `threadCloser` reads the guild's audit log (View Audit Log, else `forbidden`): a person's id, the bot, or `unknown` for Discord's own auto-archive. An archive counts only if its entry is within two minutes of the thread's `archive_timestamp`. It reads the newest 50 `THREAD_UPDATE` entries, so on a busy guild an old close may have left the log and read as `unknown`.
-- **Errors.** Every failure is a `DiscordPosterError` with a `kind`: `invalid` (refused before sending), `channel_gone`, `message_gone`, `forbidden` (a missing permission), `rejected` (Discord refused; asking again fails again) and `unavailable` (Discord or the network failed, or a rate limit held the call; `retryable`). `reason` says more for a full category (`category_full`), a channel that is no category (`not_category`) and one in no guild (`wrong_guild`). A webhook deleted by hand is found or made again once. A person who takes no direct messages is the answer `"closed"`, and a user who is not a member is `false` from `canView` and `undefined` from `memberName`, not failures. A message never holds a URL, a webhook token or the bot token.
+- **Errors.** Every failure is a `DiscordPosterError` with a `kind`: `invalid` (refused before sending), `channel_gone`, `message_gone`, `forbidden` (a missing permission), `rejected` (Discord refused; asking again fails again) and `unavailable` (Discord or the network failed, or a rate limit held the call; `retryable`). `reason` says more for a full category (`category_full`), a channel that is no category (`not_category`), a channel that is no forum or a thread that is no forum post (`not_forum`) and one in no guild (`wrong_guild`). A webhook deleted by hand is found or made again once. A person who takes no direct messages is the answer `"closed"`, and a user who is not a member is `false` from `canView` and `undefined` from `memberName`, not failures. A message never holds a URL, a webhook token or the bot token.
 
-`DISCORD_LIMITS` (frozen) holds the limits the poster checks: 2,000 characters a post, 80 for a username, 10 files and 10 MiB a post, 1 MiB for an avatar, 20 mentions, 250 pins, 100 characters for a channel name, 3,800 characters of card text, 5 card buttons and 25 menu choices.
+`DISCORD_LIMITS` (frozen) holds the limits the poster checks: 2,000 characters a post, 80 for a username, 10 files and 10 MiB a post, 1 MiB for an avatar, 20 mentions, 250 pins, 100 characters for a channel name, 3,800 characters of card text, 256 for the title of a preview card, 5 card buttons and 25 menu choices, 20 forum tags, 20 characters for a tag name and 5 tags on a post.
 
 In a test, `fakeDiscordPoster()` is a `DiscordPoster` in memory and `fakeDiscord({ poster })` or `testHost({ discord: { poster } })` gives it to the plugin; see [Testing a plugin](#testing-a-plugin). The real poster and the fake run the same scenarios, the real one over a local emulation of Discord's HTTP API.
 
@@ -4062,7 +4066,7 @@ It provides the members you give it and throws an error naming any missing membe
 `fakeScriptRunner(answer, { describe?, timeoutMs? })` is a `PrecheckScriptRunner` that runs nothing and answers `answer` (a result, an `Error` it throws, or a function of the script and its context), recording each call in `calls`; give it to `registry.useScriptRunner`.
 `fakeDiscord({ ownerId?, rootCommand?, channelContext?, poster? })` is the `DISCORD` service for a plugin that adds slash commands, reads channel context or posts through `DISCORD.poster`: give it as `services: [discord.service]`, read what the plugin added with `discord.added()`, and compose the tree Discord would get with `discord.compose()`; `channelContext` answers `DISCORD.channelContext`, by default with no context.
 Only `commands`, `guard`, `poster` and `channelContext` are given; `discord.poster` is the poster the test passed, else a new `fakeDiscordPoster()`. A plugin that reads another member of `DISCORD` in a test gives its own with `servicePair(DISCORD, { ... })`.
-`fakeDiscordPoster({ idOffset?, now? })` is a `DiscordPoster` in memory: `channels` with their messages, pins and webhook pictures, `directs`, and the knobs a test turns (`closedDirects`, `goneChannels`, `categories`, `memberNames`, `hiddenFrom`, `nonMembers`, `pinNotices`, `canReadAuditLog`, `failNext(operation, error)`, `speak`, `personCloses`, `autoArchives`, `personOpens`, `deleteWebhook`, `recreateWebhook`). `messagesIn(channelId)` lists what a channel holds. It keeps the real poster's argument checks and error kinds, a channel's two renames in ten minutes (by `now`) and the 250 pins. `idOffset` moves every id it makes, so test files that share a database never meet the same id.
+`fakeDiscordPoster({ idOffset?, now? })` is a `DiscordPoster` in memory: `channels` with their messages, pins and webhook pictures, `directs`, and the knobs a test turns (`closedDirects`, `goneChannels`, `categories`, `forums` (a forum is an entry `{ tags }` here plus a `channels` entry; a forum post is a channel whose `parentId` is the forum, with `appliedTags`), `memberNames`, `hiddenFrom`, `nonMembers`, `pinNotices`, `canReadAuditLog`, `failNext(operation, error)`, `speak`, `personCloses`, `autoArchives`, `personOpens`, `deleteWebhook`, `recreateWebhook`). `messagesIn(channelId)` lists what a channel holds. It keeps the real poster's argument checks and error kinds, a channel's two renames in ten minutes (by `now`) and the 250 pins. `idOffset` moves every id it makes, so test files that share a database never meet the same id.
 
 ### `testHost`: the built-in plugins and yours, over PostgreSQL
 
@@ -4767,6 +4771,7 @@ Import from the entries listed below; source area files are internal.
 | `fakeDiscordPoster` | `pi-roundtable/testing` | value |
 | `FakeDiscordPoster` | `pi-roundtable/testing` | type |
 | `FakePosterChannel` | `pi-roundtable/testing` | type |
+| `FakeForum` | `pi-roundtable/testing` | type |
 | `FakePosterMessage` | `pi-roundtable/testing` | type |
 | `fakePrecheck` | `pi-roundtable/testing` | value |
 | `fakePrechecks` | `pi-roundtable/testing` | value |
@@ -4988,14 +4993,21 @@ Import from the entries listed below; source area files are internal.
 | `CardPicture` | `pi-roundtable/discord` | type |
 | `CardSelect` | `pi-roundtable/discord` | type |
 | `CategoryChannel` | `pi-roundtable/discord` | type |
+| `ChannelKind` | `pi-roundtable/discord` | type |
+| `ChannelKindInfo` | `pi-roundtable/discord` | type |
 | `DiscordCard` | `pi-roundtable/discord` | type |
 | `DiscordFailure` | `pi-roundtable/discord` | type |
 | `DiscordMessage` | `pi-roundtable/discord` | type |
 | `DiscordPoster` | `pi-roundtable/discord` | type |
 | `DiscordReason` | `pi-roundtable/discord` | type |
+| `ForumPost` | `pi-roundtable/discord` | type |
+| `ForumPostCreated` | `pi-roundtable/discord` | type |
+| `ForumTag` | `pi-roundtable/discord` | type |
+| `ForumTagInput` | `pi-roundtable/discord` | type |
 | `PostedMessage` | `pi-roundtable/discord` | type |
 | `PosterFile` | `pi-roundtable/discord` | type |
 | `RecentMessage` | `pi-roundtable/discord` | type |
+| `ThreadAutoArchive` | `pi-roundtable/discord` | type |
 | `ThreadCloser` | `pi-roundtable/discord` | type |
 | `ThreadState` | `pi-roundtable/discord` | type |
 | `WebhookCardPost` | `pi-roundtable/discord` | type |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable",
-	"version": "0.30.3",
+	"version": "0.31.0",
 	"description": "A plugin-driven Pi agent server for one owner, reached through Discord or the web",
 	"type": "module",
 	"license": "MIT",

package/src/core/contract/channels.ts

@@ -76,6 +76,14 @@ export interface InboundMessage {
 	 */
 	space?: string;
 	isDirect: boolean;
+	/**
+	 * Set when the message was written in a thread (on Discord a thread of a text channel or a post
+	 * of a forum); absent in a channel and in a direct conversation. `parentId` is the thread's
+	 * parent channel and `parentKind` what it is: a post of a forum has `"forum"`, so a claim that
+	 * answers in a thread by starting one does not start another inside it. `"other"` is any parent
+	 * that is neither a text channel nor a forum, and also a parent the surface could not read.
+	 */
+	thread?: { parentId: string; parentKind: "text" | "forum" | "other" };
 	/**
 	 * Set when an integration posted the message, such as a Discord webhook; its name is
 	 * `authorName`. `own` says the integration is one the assistant posts through itself, such as an

package/src/core/discord/inbound-message.ts

@@ -1,4 +1,4 @@
-import { type Message, MessageReferenceType } from "discord.js";
+import { ChannelType, type Message, MessageReferenceType } from "discord.js";
 import type { InboundMessage } from "../contract/channels.ts";
 import { channelKey } from "../contract/surface.ts";
 import type { AttachmentRef } from "../domain/attachment.ts";
@@ -36,6 +36,26 @@ function referenceOf(referenced: Message, mention: RegExp) {
 	};
 }
 
+/** What a thread's parent is: a text channel, a forum, or something else (also a parent that cannot be read). */
+async function threadOf(
+	message: Message,
+): Promise<InboundMessage["thread"] | undefined> {
+	const { channel } = message;
+	if (!channel.isThread() || !channel.parentId) return undefined;
+	const parent =
+		channel.parent ??
+		(await channel.guild.channels.fetch(channel.parentId).catch(() => null));
+	return {
+		parentId: channel.parentId,
+		parentKind:
+			parent?.type === ChannelType.GuildText
+				? "text"
+				: parent?.type === ChannelType.GuildForum
+					? "forum"
+					: "other",
+	};
+}
+
 /**
  * The facts of one Discord message, as the neutral `InboundMessage`; undefined for the bot's own
  * messages and before the client is ready. A forward reports the channel it came from as a
@@ -66,6 +86,7 @@ export async function toInbound(
 	const roleIds = message.member
 		? [...message.member.roles.cache.keys()]
 		: undefined;
+	const thread = await threadOf(message);
 	return {
 		channel: channelKey("discord", message.channelId),
 		messageId: message.id,
@@ -97,6 +118,7 @@ export async function toInbound(
 				}
 			: {}),
 		isDirect: message.channel.isDMBased(),
+		...(thread ? { thread } : {}),
 		...(message.guildId ? { space: message.guildId } : {}),
 		mentionsBot: message.mentions.users.has(botId),
 		repliesToBot: referenced?.author.id === botId,

package/src/core/discord/poster/poster-card-parts.ts

@@ -0,0 +1,160 @@
+import {
+	type CardPicture,
+	DISCORD_LIMITS,
+	type DiscordCard,
+} from "./poster.ts";
+import { invalid } from "./poster-errors.ts";
+
+/** The longest picture address a post carries. */
+const AVATAR_URL_MAX = 2_048;
+
+/** The longest address Discord accepts on a link button. */
+const LINK_BUTTON_URL_MAX = 512;
+
+/** The longest alt text Discord takes for a thumbnail or a gallery item. */
+const PICTURE_DESCRIPTION_MAX = 1_024;
+
+/** Discord's style number for a button that opens an address. */
+const LINK_BUTTON_STYLE = 5;
+
+const BUTTON_STYLES = {
+	primary: 1,
+	secondary: 2,
+	success: 3,
+	danger: 4,
+} as const;
+
+export function isHttps(url: string | undefined): url is string {
+	if (url === undefined || url.length > AVATAR_URL_MAX) return false;
+	try {
+		return new URL(url).protocol === "https:";
+	} catch {
+		return false;
+	}
+}
+
+/** The checked wire form of a card's picture: an `https` address, and an alt text of 1 to 1,024 characters when given. */
+export function checkPicture(label: string, picture: CardPicture) {
+	if (!(isHttps(picture.url) && picture.url === picture.url.trim()))
+		throw invalid(
+			`${label} has an https address of at most ${AVATAR_URL_MAX} characters`,
+		);
+	const { description } = picture;
+	if (
+		description !== undefined &&
+		(description === "" || [...description].length > PICTURE_DESCRIPTION_MAX)
+	)
+		throw invalid(
+			`${label} has a description of 1 to ${PICTURE_DESCRIPTION_MAX} characters`,
+		);
+	return {
+		media: { url: picture.url },
+		...(description === undefined ? {} : { description }),
+	};
+}
+
+/** Refuses a card whose text would not fit one message, so a caller shortens it first. */
+export function checkCardTextSize(texts: readonly string[]): void {
+	const size = texts.reduce((sum, text) => sum + [...text].length, 0);
+	if (size > DISCORD_LIMITS.cardTextChars)
+		throw invalid(
+			`a card holds at most ${DISCORD_LIMITS.cardTextChars} characters of text; shorten it first`,
+		);
+	if (texts.some((text) => text.trim() === ""))
+		throw invalid("a card has no empty text");
+}
+
+/**
+ * The checked action rows of a card, in Discord's wire form: a row for each menu, then one row of
+ * the buttons and link buttons. A Components V2 container and a legacy message hold the same rows.
+ */
+export function cardRows(card: DiscordCard) {
+	const buttons = card.buttons ?? [];
+	const links = card.links ?? [];
+	if (buttons.length + links.length > DISCORD_LIMITS.cardButtons)
+		throw invalid(`a card holds at most ${DISCORD_LIMITS.cardButtons} buttons`);
+	for (const link of links) {
+		if (link.label === "" || [...link.label].length > 80)
+			throw invalid("a link button has a label of 1 to 80 characters");
+		if (
+			!link.url.startsWith("https://") ||
+			[...link.url].length > LINK_BUTTON_URL_MAX
+		)
+			throw invalid(
+				`a link button has an https address of at most ${LINK_BUTTON_URL_MAX} characters`,
+			);
+	}
+	const selects = card.selects ?? [];
+	for (const select of selects) {
+		if (
+			select.customId === "" ||
+			[...select.customId].length > 100 ||
+			select.placeholder === "" ||
+			[...select.placeholder].length > 150 ||
+			select.options.length < 1 ||
+			select.options.length > DISCORD_LIMITS.selectOptions ||
+			select.options.some(
+				(option) =>
+					option.label === "" ||
+					[...option.label].length > 100 ||
+					option.value === "" ||
+					[...option.value].length > 100,
+			)
+		)
+			throw invalid(
+				"a menu has an id of 1 to 100 characters, a placeholder of 1 to 150 and 1 to 25 choices of 1 to 100 characters",
+			);
+	}
+	for (const button of buttons) {
+		if (
+			button.customId === "" ||
+			[...button.customId].length > 100 ||
+			button.label === "" ||
+			[...button.label].length > 80
+		)
+			throw invalid(
+				"a button has an id of 1 to 100 characters and a label of 1 to 80",
+			);
+	}
+	return [
+		...selects.map((select) => ({
+			type: 1,
+			components: [
+				{
+					type: 3,
+					custom_id: select.customId,
+					placeholder: select.placeholder,
+					min_values: 1,
+					max_values: 1,
+					options: select.options.map((option) => ({
+						label: option.label,
+						value: option.value,
+						...(option.selected ? { default: true } : {}),
+					})),
+				},
+			],
+		})),
+		...(buttons.length + links.length > 0
+			? [
+					{
+						type: 1,
+						components: [
+							...buttons.map((button) => ({
+								type: 2,
+								style: BUTTON_STYLES[button.style],
+								label: button.label,
+								custom_id: button.customId,
+								...(button.disabled ? { disabled: true } : {}),
+							})),
+							...links.map((link) => ({
+								type: 2,
+								style: LINK_BUTTON_STYLE,
+								label: link.label,
+								url: link.url,
+							})),
+						],
+					},
+				]
+			: []),
+	];
+}

package/src/core/discord/poster/poster-checks.ts

@@ -1,41 +1,26 @@
 import {
-	type CardPicture,
 	DISCORD_LIMITS,
 	type DiscordCard,
 	type WebhookCardPost,
 	type WebhookPost,
 } from "./poster.ts";
-import { DiscordPosterError } from "./poster-errors.ts";
+import {
+	cardRows,
+	checkCardTextSize,
+	checkPicture,
+	isHttps,
+} from "./poster-card-parts.ts";
+import { invalid } from "./poster-errors.ts";
+import { legacyCardBody } from "./poster-legacy-card.ts";
+
+export { invalid };
 
 /** The flag that makes a message a Components V2 message. */
 export const COMPONENTS_V2_FLAG = 1 << 15;
 
-/** The longest picture address a post carries. */
-const AVATAR_URL_MAX = 2_048;
-
-/** The longest address Discord accepts on a link button. */
-const LINK_BUTTON_URL_MAX = 512;
-
-/** The longest alt text Discord takes for a thumbnail or a gallery item. */
-const PICTURE_DESCRIPTION_MAX = 1_024;
-
-/** Discord's style number for a button that opens an address. */
-const LINK_BUTTON_STYLE = 5;
-
-const BUTTON_STYLES = {
-	primary: 1,
-	secondary: 2,
-	success: 3,
-	danger: 4,
-} as const;
-
 const SNOWFLAKE = /^[0-9]{17,20}$/;
 const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
 
-export function invalid(message: string): DiscordPosterError {
-	return new DiscordPosterError("invalid", message);
-}
-
 /** Refuses an id that is not a Discord id before it is put in a route. */
 export function checkSnowflake(label: string, value: string): string {
 	if (!SNOWFLAKE.test(value))
@@ -140,35 +125,6 @@ export function checkedPost(post: WebhookPost) {
 	};
 }
 
-/** The checked wire form of a card's picture: an `https` address, and an alt text of 1 to 1,024 characters when given. */
-function checkPicture(label: string, picture: CardPicture) {
-	if (!(isHttps(picture.url) && picture.url === picture.url.trim()))
-		throw invalid(
-			`${label} has an https address of at most ${AVATAR_URL_MAX} characters`,
-		);
-	const { description } = picture;
-	if (
-		description !== undefined &&
-		(description === "" || [...description].length > PICTURE_DESCRIPTION_MAX)
-	)
-		throw invalid(
-			`${label} has a description of 1 to ${PICTURE_DESCRIPTION_MAX} characters`,
-		);
-	return {
-		media: { url: picture.url },
-		...(description === undefined ? {} : { description }),
-	};
-}
-
-function isHttps(url: string | undefined): url is string {
-	if (url === undefined || url.length > AVATAR_URL_MAX) return false;
-	try {
-		return new URL(url).protocol === "https:";
-	} catch {
-		return false;
-	}
-}
-
 /** Whether the bytes are a PNG no larger than a webhook avatar may be. */
 export function checkAvatar(png: Uint8Array): void {
 	if (png.byteLength > DISCORD_LIMITS.avatarBytes)
@@ -189,22 +145,19 @@ export function checkChannelName(label: string, name: string): void {
 }
 
 /**
- * The body of a card: a container (with a colour bar when `accent` is set) holding the heading, a
- * divider, one text block per section and a quiet line at the end. It refuses a card whose text
- * would not fit one message, so a caller shortens it first. No mention in it pings.
+ * The body of a card. A card with a `preview` is a legacy message (see `legacyCardBody`); any
+ * other is a Components V2 message: a container (with a colour bar when `accent` is set) holding
+ * the heading, a divider, one text block per section and a quiet line at the end. It refuses a
+ * card whose text would not fit one message, so a caller shortens it first. No mention in it pings.
  */
 export function cardBody(card: DiscordCard) {
+	if (card.preview !== undefined)
+		return legacyCardBody({ ...card, preview: card.preview });
 	const heading = `### ${card.title}`;
 	const main = [heading, ...card.sections.filter((section) => section !== "")];
 	const footer = card.footer ? [`-# ${card.footer}`] : [];
 	const texts = [...main, ...footer];
-	const size = texts.reduce((sum, text) => sum + [...text].length, 0);
-	if (size > DISCORD_LIMITS.cardTextChars)
-		throw invalid(
-			`a card holds at most ${DISCORD_LIMITS.cardTextChars} characters of text; shorten it first`,
-		);
-	if (texts.some((text) => text.trim() === ""))
-		throw invalid("a card has no empty text");
+	checkCardTextSize(texts);
 	const [first, ...rest] = main;
 	const thumbnail = card.thumbnail
 		? checkPicture("a card's thumbnail", card.thumbnail)
@@ -212,53 +165,6 @@ export function cardBody(card: DiscordCard) {
 	const image = card.image
 		? checkPicture("a card's image", card.image)
 		: undefined;
-	const buttons = card.buttons ?? [];
-	const links = card.links ?? [];
-	if (buttons.length + links.length > DISCORD_LIMITS.cardButtons)
-		throw invalid(`a card holds at most ${DISCORD_LIMITS.cardButtons} buttons`);
-	for (const link of links) {
-		if (link.label === "" || [...link.label].length > 80)
-			throw invalid("a link button has a label of 1 to 80 characters");
-		if (
-			!link.url.startsWith("https://") ||
-			[...link.url].length > LINK_BUTTON_URL_MAX
-		)
-			throw invalid(
-				`a link button has an https address of at most ${LINK_BUTTON_URL_MAX} characters`,
-			);
-	}
-	const selects = card.selects ?? [];
-	for (const select of selects) {
-		if (
-			select.customId === "" ||
-			[...select.customId].length > 100 ||
-			select.placeholder === "" ||
-			[...select.placeholder].length > 150 ||
-			select.options.length < 1 ||
-			select.options.length > DISCORD_LIMITS.selectOptions ||
-			select.options.some(
-				(option) =>
-					option.label === "" ||
-					[...option.label].length > 100 ||
-					option.value === "" ||
-					[...option.value].length > 100,
-			)
-		)
-			throw invalid(
-				"a menu has an id of 1 to 100 characters, a placeholder of 1 to 150 and 1 to 25 choices of 1 to 100 characters",
-			);
-	}
-	for (const button of buttons) {
-		if (
-			button.customId === "" ||
-			[...button.customId].length > 100 ||
-			button.label === "" ||
-			[...button.label].length > 80
-		)
-			throw invalid(
-				"a button has an id of 1 to 100 characters and a label of 1 to 80",
-			);
-	}
 	return {
 		flags: COMPONENTS_V2_FLAG,
 		components: [
@@ -279,45 +185,7 @@ export function cardBody(card: DiscordCard) {
 					...rest.map((content) => ({ type: 10, content })),
 					...(image ? [{ type: 12, items: [image] }] : []),
 					...footer.map((content) => ({ type: 10, content })),
-					...selects.map((select) => ({
-						type: 1,
-						components: [
-							{
-								type: 3,
-								custom_id: select.customId,
-								placeholder: select.placeholder,
-								min_values: 1,
-								max_values: 1,
-								options: select.options.map((option) => ({
-									label: option.label,
-									value: option.value,
-									...(option.selected ? { default: true } : {}),
-								})),
-							},
-						],
-					})),
-					...(buttons.length + links.length > 0
-						? [
-								{
-									type: 1,
-									components: [
-										...buttons.map((button) => ({
-											type: 2,
-											style: BUTTON_STYLES[button.style],
-											label: button.label,
-											custom_id: button.customId,
-											...(button.disabled ? { disabled: true } : {}),
-										})),
-										...links.map((link) => ({
-											type: 2,
-											style: LINK_BUTTON_STYLE,
-											label: link.label,
-											url: link.url,
-										})),
-									],
-								},
-							]
-						: []),
+					...cardRows(card),
 				],
 			},
 		],

package/src/core/discord/poster/poster-errors.ts

@@ -11,9 +11,13 @@ export type DiscordFailure =
 
 /**
  * More about why Discord refused, where its code alone does not say: a category that is full (a
- * 400 with a form-body error) and a channel that is no category or in no right guild.
+ * 400 with a form-body error), a channel that is no category or forum, and one in no right guild.
  */
-export type DiscordReason = "category_full" | "not_category" | "wrong_guild";
+export type DiscordReason =
+	| "category_full"
+	| "not_category"
+	| "not_forum" // a forum call on a channel that is no forum, or a post call on a thread that is no forum post
+	| "wrong_guild";
 
 /**
  * A failed Discord call. The message names the operation and Discord's own reason, never a URL,
@@ -104,3 +108,8 @@ export function failure(operation: string, error: unknown): DiscordPosterError {
 export function isCode(error: unknown, ...codes: number[]): boolean {
 	return error instanceof DiscordAPIError && codes.includes(Number(error.code));
 }
+
+/** A call refused before it was sent, for an argument Discord would refuse. */
+export function invalid(message: string): DiscordPosterError {
+	return new DiscordPosterError("invalid", message);
+}