City role bot

Starboard

The starboard is configured in src/starboard.ts for guild 1244870846556803074, posting to channel 1559594091497660507.

Messages qualify when five unique people react with any combination of ⭐, 🔥, 😭, and 🍅. Each person counts once across all four emoji and normal/super reactions. Bot votes and the original author's votes do not count. Reposts show separate counts, such as ⭐ 3 🔥 5 😭 4, using unique eligible people per emoji. Zero-count emoji are omitted. The reaction summary is followed on the next line by the raw, unmasked original-message URL, which Discord can render as a message link. There is no separate channel mention. These counts can overlap; qualification still uses five unique people across all eligible emoji, not the sum of the displayed counts.

All readable message-bearing channels and accessible threads are eligible, including archived threads. Current and previously used starboard destinations and their threads are excluded to avoid reposting old highlights.

Set STARBOARD_EXCLUDED_CHANNEL_IDS in .env to a comma-separated list of source channel IDs, then restart the bot. It defaults to 1308583779157151804; an explicitly empty value clears the configurable exclusions. Exclusions also apply to child channels/threads, live reactions, and candidates already in the saved backfill queue. Existing Discord reposts are not deleted automatically. /starboard status shows the configured list.

Restricted-channel messages can be copied into the destination, so give the bot access only to channels whose messages may be shared there.

Reposts include author attribution, text, the first non-spoiler image attachment, attachment links, individual emoji counts, and a link to the original. Replies also include the replied-to author's name, a short text preview, and a link to that message in an embed field. Deleted or inaccessible reply targets display an unavailable notice without preventing the reply from being reposted.

Rich embeds, stickers, polls, and forwarded-message snapshots are not reconstructed; use the original link for those. Text, reply previews, and attachment lists are bounded by Discord's embed limits. Spoiler images are not displayed automatically.

Reposts remain if their score falls below five, and update when reactions or the original text/attachments change. Deleting the original removes its repost. Missing access does not count as deletion. Manually deleting a repost can result in its recreation when the original is next reconciled.

Discord setup

Enable Message Content Intent in the Developer Portal. The bot requests it along with guild message and reaction events.

In source channels it needs View Channel and Read Message History. In the destination it also needs Send Messages and Embed Links. It can enumerate joined archived private threads without Manage Threads; enumerating other archived private threads requires Manage Threads. Discord still determines which history the bot may read. Deleted messages and inaccessible history cannot be recovered.

Backfill

On first startup, the bot starts a full-history scan with no age cutoff. It paginates messages and public/private archived thread lists, respects Discord's rate limits, and pauses briefly between pages to leave room for live events.

Backfill has two resumable phases:

1. Collect: scan every accessible source, saving potentially qualifying message IDs and source channel IDs without creating reposts.
2. Post: sort candidates by creation order across the whole server, oldest first, then fetch each original again and check its current unique-person eligibility before posting.

Full message contents are not retained in the queue. New live candidates wait while backfill runs, including while it is paused. Candidates arriving during collection join the history queue; those arriving during posting wait until the history queue has been processed. Existing reposts can still update or be deleted.

Mappings and scan checkpoints are saved atomically in data/starboard.json. Restarts reconcile existing reposts and resume unfinished scans. Connection failures, timeouts, and server errors are retried with exponential backoff (1, 2, 4, and 8 seconds). If retries are exhausted, backfill pauses without advancing its current page or queued candidate. Permission errors are not retried; inaccessible history or thread-list endpoints are skipped and reported in logs and status. Recent send retries also use Discord nonce deduplication. Run only one bot process against this data directory, and retain it across deployments.

Changing the configured destination archives the previous destination's mappings locally. The new destination reuses the collected history: already-posted originals, remaining history candidates, and waiting live candidates are merged and posted oldest-first. If collection was still running, its cursors are preserved. Old Discord reposts are not edited or deleted. Originals are fetched again and must still qualify before being posted to the new destination.

Legacy state without a destination ID belongs to the original channel 1559288341717844088. State from before the two-phase backfill requires a fresh history scan because it did not retain a candidate queue.

Server admins with Manage Server can use:

• /starboard status — settings, repost count, scan progress, and failures.
• /starboard backfill — resume a paused scan; after a completed scan, start a fresh full-history scan without duplicating tracked reposts.

A completed scan does not automatically restart on every boot. Reactions added while the bot was offline to previously untracked messages require another full scan, or a later live reaction event on those messages. Run backfill again after adding access to previously skipped channels.

Development

pnpm-workspace.yaml applies the checked-in Oceanic 1.14.0 patch in patches/. It fixes transport failures leaving REST promises unresolved and clears their request timers. Client errors are logged; starboard operations can then retry instead of crashing or hanging. Install dependencies with pnpm so this patch is applied.

• pnpm check — type-check source and tests.
• pnpm test — offline starboard tests (does not connect to Discord).
• pnpm start — start the bot using .env.