@helyx/bot 0.4.8 → 0.4.11

package/dist/events.js

@@ -1,7 +1,22 @@
 import { HELYX_SERVICE_NAMES } from "@helyx/sdk";
-import { ChannelType, Events, PermissionFlagsBits, RESTJSONErrorCodes, } from "discord.js";
+import { ChannelType, Events, GatewayIntentBits, PermissionFlagsBits, RESTJSONErrorCodes, } from "discord.js";
 import { toReplyOptions } from "./interactions.js";
+import { createHash } from "node:crypto";
+import { classifyGuildMessage, unavailableGuildMessageClassification, } from "./message-classification.js";
 export function installModuleEvents(client, modules, logger, services) {
+    const privilegedMessageContributions = modules.flatMap((module) => (module.events?.privilegedMessageCreate ?? []).map((contribution) => ({
+        moduleId: module.manifest.id,
+        contribution,
+    })));
+    const guildMessageContributions = modules.flatMap((module) => (module.events?.guildMessageCreate ?? []).map((contribution) => ({
+        moduleId: module.manifest.id,
+        classificationRequested: module.requiredDiscordCapabilities?.includes("message-content") ??
+            false,
+        contribution,
+    })));
+    const messageClassificationRequested = modules.some((module) => module.requiredDiscordCapabilities?.includes("message-content"));
+    const messageClassificationAvailable = messageClassificationRequested &&
+        client.options.intents.has(GatewayIntentBits.MessageContent);
     const reactionContributions = modules.flatMap((module) => (module.events?.messageReactionAdd ?? []).map((contribution) => ({
         moduleId: module.manifest.id,
         contribution,
@@ -18,6 +33,10 @@ export function installModuleEvents(client, modules, logger, services) {
         moduleId: module.manifest.id,
         contribution,
     })));
+    const memberRemoveContributions = modules.flatMap((module) => (module.events?.guildMemberRemove ?? []).map((contribution) => ({
+        moduleId: module.manifest.id,
+        contribution,
+    })));
     const guildRoleDeleteContributions = modules.flatMap((module) => (module.events?.guildRoleDelete ?? []).map((contribution) => ({
         moduleId: module.manifest.id,
         contribution,
@@ -42,10 +61,13 @@ export function installModuleEvents(client, modules, logger, services) {
         moduleId: module.manifest.id,
         contribution,
     })));
-    if (reactionContributions.length === 0 &&
+    if (privilegedMessageContributions.length === 0 &&
+        guildMessageContributions.length === 0 &&
+        reactionContributions.length === 0 &&
         reactionRemoveContributions.length === 0 &&
         messageDeleteContributions.length === 0 &&
         memberAddContributions.length === 0 &&
+        memberRemoveContributions.length === 0 &&
         guildRoleDeleteContributions.length === 0 &&
         guildRoleUpdateContributions.length === 0 &&
         channelDeleteContributions.length === 0 &&
@@ -54,6 +76,59 @@ export function installModuleEvents(client, modules, logger, services) {
         guildEmojiUpdateContributions.length === 0)
         return { stop: () => Promise.resolve(), queueDepth: () => 0 };
     const queue = new BoundedGuildEventQueue(logger);
+    const privilegedEligibilityQueue = privilegedMessageContributions.length > 0
+        ? new BoundedGuildEventQueue(logger)
+        : null;
+    const guildMessageQueue = guildMessageContributions.length > 0
+        ? new BoundedGuildEventQueue(logger)
+        : null;
+    if (privilegedMessageContributions.length > 0) {
+        client.on(Events.MessageCreate, (message) => {
+            if (!message.guildId || !privilegedEligibilityQueue)
+                return;
+            privilegedEligibilityQueue.enqueue(message.guildId, async () => {
+                const installations = services.get(HELYX_SERVICE_NAMES.installations);
+                const eligible = [];
+                for (const item of privilegedMessageContributions) {
+                    try {
+                        if ((await installations.isModuleEnabled(message.guildId, item.moduleId)) &&
+                            (await item.contribution.isEligible({
+                                serverId: message.guildId,
+                                channelId: message.channelId,
+                                services,
+                            }))) {
+                            eligible.push(item);
+                        }
+                    }
+                    catch (error) {
+                        logger.warn({
+                            event: "module.privileged_message_eligibility_failed",
+                            moduleId: item.moduleId,
+                            error: safeError(error),
+                            guildId: message.guildId,
+                            channelId: message.channelId,
+                        }, "Module privileged message eligibility failed");
+                    }
+                }
+                if (eligible.length > 0) {
+                    queue.enqueue(message.guildId, () => handlePrivilegedMessageCreate(message, eligible));
+                }
+            });
+        });
+    }
+    if (guildMessageContributions.length > 0) {
+        client.on(Events.MessageCreate, (message) => {
+            if (!message.guildId ||
+                !guildMessageQueue ||
+                message.author.bot ||
+                message.author.system ||
+                Boolean(message.webhookId) ||
+                message.system) {
+                return;
+            }
+            guildMessageQueue.enqueue(message.guildId, () => handleGuildMessageCreate(message));
+        });
+    }
     if (reactionContributions.length > 0) {
         client.on(Events.MessageReactionAdd, (reaction, user, details) => {
             const guildId = reaction.message.guildId;
@@ -79,6 +154,11 @@ export function installModuleEvents(client, modules, logger, services) {
             queue.enqueue(member.guild.id, () => handleMemberAdd(member));
         });
     }
+    if (memberRemoveContributions.length > 0) {
+        client.on(Events.GuildMemberRemove, (member) => {
+            queue.enqueue(member.guild.id, () => handleMemberRemove(member));
+        });
+    }
     if (guildRoleDeleteContributions.length > 0) {
         client.on(Events.GuildRoleDelete, (role) => {
             queue.enqueue(role.guild.id, () => handleResourceLifecycle(guildRoleDeleteContributions, role.guild.id, "roleId", role.id, "guild_role_delete"));
@@ -137,6 +217,116 @@ export function installModuleEvents(client, modules, logger, services) {
             }
         }
     }
+    async function handlePrivilegedMessageCreate(message, contributions) {
+        if (!message.guildId || !message.channelId)
+            return;
+        for (const { moduleId, contribution } of contributions) {
+            try {
+                await contribution.execute({
+                    serverId: message.guildId,
+                    channelId: message.channelId,
+                    messageId: message.id,
+                    userId: message.author.id,
+                    userIsBot: message.author.bot,
+                    webhookId: message.webhookId,
+                    content: message.content,
+                    services,
+                    deleteSource: async () => {
+                        await message.delete();
+                    },
+                });
+            }
+            catch (error) {
+                logger.warn({
+                    event: "module.privileged_message_create_failed",
+                    moduleId,
+                    error: safeError(error),
+                    messageId: message.id,
+                    guildId: message.guildId,
+                }, "Module privileged message-create event failed");
+            }
+        }
+    }
+    async function handleGuildMessageCreate(message) {
+        if (!message.guildId || !message.channelId)
+            return;
+        const installations = services.get(HELYX_SERVICE_NAMES.installations);
+        const parentChannelId = message.channel.isThread()
+            ? (message.channel.parentId ?? undefined)
+            : undefined;
+        const authorRoleIds = message.member
+            ? [...message.member.roles.cache.keys()].sort((left, right) => left.localeCompare(right, "en"))
+            : [];
+        const authorDisplayName = message.member?.displayName ??
+            message.author.globalName ??
+            message.author.username;
+        let classifiedMessage;
+        for (const { moduleId, classificationRequested, contribution, } of guildMessageContributions) {
+            try {
+                if (!(await installations.isModuleEnabled(message.guildId, moduleId))) {
+                    continue;
+                }
+                await contribution.execute({
+                    serverId: message.guildId,
+                    channelId: message.channelId,
+                    ...(parentChannelId ? { parentChannelId } : {}),
+                    messageId: message.id,
+                    authorId: message.author.id,
+                    authorDisplayName,
+                    authorRoleIds,
+                    authorIsBot: false,
+                    authorIsWebhook: false,
+                    authorIsSystem: false,
+                    get classification() {
+                        if (!classificationRequested || !messageClassificationAvailable)
+                            return unavailableGuildMessageClassification;
+                        classifiedMessage ??= classifyGuildMessage(message);
+                        return classifiedMessage;
+                    },
+                    createdAt: message.createdAt,
+                    services,
+                    addAuthorRole: async (roleId) => {
+                        await services
+                            .get(HELYX_SERVICE_NAMES.memberRoles)
+                            .addApprovedRole({
+                            guildId: message.guildId,
+                            memberUserId: message.author.id,
+                            roleId,
+                            moduleId,
+                            reason: "Guild message contribution author role addition",
+                        });
+                    },
+                    removeAuthorRole: async (roleId) => {
+                        await services
+                            .get(HELYX_SERVICE_NAMES.memberRoles)
+                            .removeApprovedRole({
+                            guildId: message.guildId,
+                            memberUserId: message.author.id,
+                            roleId,
+                            moduleId,
+                            reason: "Guild message contribution author role removal",
+                        });
+                    },
+                    sendToChannel: (channelId, response) => services
+                        .get(HELYX_SERVICE_NAMES.discordMessages)
+                        .send({
+                        guildId: message.guildId,
+                        channelId,
+                        response,
+                    }),
+                });
+            }
+            catch (error) {
+                logger.warn({
+                    event: "module.guild_message_create_failed",
+                    moduleId,
+                    error: safeError(error),
+                    messageId: message.id,
+                    guildId: message.guildId,
+                }, "Module guild message-create event failed");
+            }
+        }
+    }
     async function handleReaction(receivedReaction, receivedUser, burst) {
         try {
             const user = receivedUser.partial
@@ -197,6 +387,8 @@ export function installModuleEvents(client, modules, logger, services) {
         }
     }
     async function handleMemberAdd(member) {
+        if (!member.joinedAt)
+            throw new Error("Discord member join timestamp is unavailable");
         const installations = services.get(HELYX_SERVICE_NAMES.installations);
         for (const { moduleId, contribution } of memberAddContributions) {
             try {
@@ -209,6 +401,8 @@ export function installModuleEvents(client, modules, logger, services) {
                     memberId: member.id,
                     memberDisplayName: member.displayName,
                     memberIsBot: member.user.bot,
+                    accountCreatedAt: member.user.createdAt,
+                    joinedAt: member.joinedAt,
                     services,
                     assignRole: (roleId) => assignMemberRole(member, roleId),
                     sendToChannel: (channelId, response) => sendToGuildChannel(member, channelId, response),
@@ -225,6 +419,33 @@ export function installModuleEvents(client, modules, logger, services) {
             }
         }
     }
+    async function handleMemberRemove(member) {
+        const installations = services.get(HELYX_SERVICE_NAMES.installations);
+        for (const { moduleId, contribution } of memberRemoveContributions) {
+            try {
+                if (!(await installations.isModuleEnabled(member.guild.id, moduleId))) {
+                    continue;
+                }
+                await contribution.execute({
+                    serverId: member.guild.id,
+                    memberId: member.id,
+                    memberIsBot: member.user.bot,
+                    accountCreatedAt: member.user.createdAt,
+                    joinedAt: member.joinedAt,
+                    services,
+                });
+            }
+            catch (error) {
+                logger.warn({
+                    event: "module.member_remove_failed",
+                    moduleId,
+                    error: safeError(error),
+                    memberId: member.id,
+                    guildId: member.guild.id,
+                }, "Module member-remove event failed");
+            }
+        }
+    }
     async function handleReactionRemove(receivedReaction, receivedUser, burst) {
         try {
             if (receivedUser.bot)
@@ -293,7 +514,16 @@ export function installModuleEvents(client, modules, logger, services) {
             }
         }
     }
-    return { stop: () => queue.stop(), queueDepth: () => queue.queueDepth() };
+    return {
+        stop: async () => {
+            await privilegedEligibilityQueue?.stop();
+            await guildMessageQueue?.stop();
+            await queue.stop();
+        },
+        queueDepth: () => queue.queueDepth() +
+            (privilegedEligibilityQueue?.queueDepth() ?? 0) +
+            (guildMessageQueue?.queueDepth() ?? 0),
+    };
 }
 class BoundedGuildEventQueue {
     logger;
@@ -405,11 +635,183 @@ const dangerousRolePermissionNames = new Set([
     "MUTE_MEMBERS",
     "VIEW_AUDIT_LOG",
 ]);
+const directMessageAttemptTimeoutMs = 5_000;
+const guildChannelAudienceInspectionLimit = 500;
+export class DiscordMessageDeliveryService {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async send(input) {
+        validateSnowflake(input.guildId, "guild");
+        validateSnowflake(input.channelId, "channel");
+        const guild = await this.client.guilds.fetch(input.guildId);
+        if (guild.id !== input.guildId)
+            throw new Error("Discord guild validation failed");
+        const channel = await guild.channels.fetch(input.channelId);
+        if (!channel ||
+            channel.guild.id !== guild.id ||
+            !channel.isSendable() ||
+            channel.isDMBased()) {
+            throw new Error("Discord message channel is unavailable");
+        }
+        const me = guild.members.me ?? (await guild.members.fetchMe());
+        const effective = channel.permissionsFor(me);
+        if (!effective?.has(PermissionFlagsBits.ViewChannel) ||
+            !effective.has(PermissionFlagsBits.SendMessages)) {
+            throw new Error("Discord message channel permissions are unavailable");
+        }
+        const options = {
+            ...toReplyOptions({ ...input.response, ephemeral: false }),
+        };
+        if (input.idempotencyKey) {
+            const nonce = createHash("sha256")
+                .update(input.idempotencyKey)
+                .digest("hex")
+                .slice(0, 24);
+            options.nonce = nonce;
+            options.enforceNonce = true;
+        }
+        const message = await channel.send(options);
+        if (message.guildId !== guild.id ||
+            message.channelId !== channel.id ||
+            !discordSnowflake.test(message.id)) {
+            throw new Error("Discord sent message validation failed");
+        }
+        return { messageId: message.id };
+    }
+    async sendDirect(input) {
+        validateSnowflake(input.userId, "user");
+        try {
+            const user = await this.client.users.fetch(input.userId);
+            if (user.id !== input.userId)
+                throw new Error("Discord user validation failed");
+            const options = toReplyOptions({ ...input.response, ephemeral: false });
+            const message = await user.send(options);
+            if (!discordSnowflake.test(message.id)) {
+                return { outcome: "failed" };
+            }
+            return { outcome: "sent", messageId: message.id };
+        }
+        catch (error) {
+            return {
+                outcome: isClosedDirectMessage(error) ? "closed" : "failed",
+            };
+        }
+    }
+}
+export class DiscordMemberEnforcementService {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async kick(input) {
+        validateEnforcementMetadata(input);
+        const directMessage = input.directMessage
+            ? await this.#sendBestEffortDirectMessage(input.memberUserId, input.directMessage)
+            : "not_requested";
+        const guild = await this.client.guilds
+            .fetch(input.guildId)
+            .catch(() => null);
+        if (!guild)
+            return { outcome: "failed", directMessage };
+        if (guild.id !== input.guildId)
+            throw new Error("Discord guild validation failed");
+        let member;
+        try {
+            member = await guild.members.fetch(input.memberUserId);
+        }
+        catch (error) {
+            if (isUnknownMember(error))
+                return { outcome: "member_missing", directMessage };
+            return { outcome: "failed", directMessage };
+        }
+        if (!member)
+            return { outcome: "member_missing", directMessage };
+        if (member.id !== input.memberUserId || member.guild.id !== guild.id)
+            throw new Error("Discord member validation failed");
+        const me = guild.members.me ?? (await guild.members.fetchMe());
+        if (!me.permissions.has(PermissionFlagsBits.KickMembers)) {
+            return { outcome: "missing_permission", directMessage };
+        }
+        if (!member.kickable) {
+            return { outcome: "hierarchy_blocked", directMessage };
+        }
+        let stillRequired;
+        try {
+            stillRequired = await input.revalidate();
+        }
+        catch {
+            return { outcome: "failed", directMessage };
+        }
+        if (!stillRequired) {
+            return { outcome: "no_longer_required", directMessage };
+        }
+        try {
+            await member.kick(discordAuditReason(input));
+            return { outcome: "kicked", directMessage };
+        }
+        catch (error) {
+            if (isUnknownMember(error)) {
+                return { outcome: "member_missing", directMessage };
+            }
+            return { outcome: "failed", directMessage };
+        }
+    }
+    async #sendBestEffortDirectMessage(memberUserId, response) {
+        const attempt = async () => {
+            try {
+                const user = await this.client.users.fetch(memberUserId);
+                if (user.id !== memberUserId)
+                    throw new Error("Discord user validation failed");
+                const options = toReplyOptions({ ...response, ephemeral: false });
+                await user.send(options);
+                return "sent";
+            }
+            catch (error) {
+                return isClosedDirectMessage(error) ? "closed" : "failed";
+            }
+        };
+        return new Promise((resolve) => {
+            let settled = false;
+            const timer = setTimeout(() => {
+                settled = true;
+                resolve("failed");
+            }, directMessageAttemptTimeoutMs);
+            timer.unref();
+            void attempt().then((result) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                resolve(result);
+            });
+        });
+    }
+}
 export class DiscordMemberRoleService {
     client;
     constructor(client) {
         this.client = client;
     }
+    async createApprovedRole(input) {
+        validateRoleCreationMetadata(input);
+        const guild = await this.client.guilds.fetch(input.guildId);
+        if (guild.id !== input.guildId)
+            throw new Error("Discord guild validation failed");
+        const me = guild.members.me ?? (await guild.members.fetchMe());
+        if (!me.permissions.has(PermissionFlagsBits.ManageRoles))
+            throw new Error("Helyx requires Manage Roles to create this reward role");
+        const role = await guild.roles.create({
+            name: input.name,
+            permissions: [],
+            reason: discordAuditReason(input),
+        });
+        if (role.guild.id !== guild.id)
+            throw new Error("Created Discord role did not belong to this guild");
+        await fetchSafeRole(guild, role.id);
+        return { roleId: role.id, name: role.name };
+    }
     async getCurrentRoleIds(input) {
         const { member } = await this.fetchGuildAndMember(input);
         return [...member.roles.cache.keys()];
@@ -452,10 +854,10 @@ export class DiscordMemberRoleService {
         const addedRoles = addedIds.map((roleId) => approvedRoles.get(roleId));
         const removedRoles = removedIds.map((roleId) => approvedRoles.get(roleId));
         const reason = discordAuditReason(input);
-        if (removedRoles.length > 0)
-            await member.roles.remove(removedRoles, reason);
         if (addedRoles.length > 0)
             await member.roles.add(addedRoles, reason);
+        if (removedRoles.length > 0)
+            await member.roles.remove(removedRoles, reason);
         return { added: addedIds, removed: removedIds };
     }
     async fetchGuildAndMember(input) {
@@ -475,6 +877,32 @@ export class DiscordResourceInspection {
     constructor(client) {
         this.client = client;
     }
+    async inspectGuildCapabilities(input) {
+        validateSnowflake(input.guildId, "guild");
+        const guild = await this.client.guilds.fetch(input.guildId);
+        if (guild.id !== input.guildId)
+            throw new Error("Discord guild validation failed");
+        const me = guild.members.me ?? (await guild.members.fetchMe());
+        const effectivePermissionNames = me.permissions
+            .toArray()
+            .map(normalizePermissionName)
+            .sort();
+        return {
+            guildId: guild.id,
+            effectivePermissionNames,
+            manageRoles: me.permissions.has(PermissionFlagsBits.ManageRoles),
+            kickMembers: me.permissions.has(PermissionFlagsBits.KickMembers),
+        };
+    }
+    inspectRuntimeCapabilities() {
+        const intents = this.client.options.intents;
+        return Promise.resolve({
+            guildMembers: intents.has(GatewayIntentBits.GuildMembers),
+            guildMessages: intents.has(GatewayIntentBits.GuildMessages),
+            guildMessageReactions: intents.has(GatewayIntentBits.GuildMessageReactions),
+            messageContent: intents.has(GatewayIntentBits.MessageContent),
+        });
+    }
     async resolveMemberSnapshots(input) {
         const guild = await this.#resolveMemberGuild(input);
         return Promise.all(input.userIds.map(async (userId) => {
@@ -502,12 +930,41 @@ export class DiscordResourceInspection {
                     return null;
                 throw error;
             });
+            const avatarUrl = memberAvatarUrl(member);
             return {
                 userId,
                 displayName: member?.displayName ?? null,
+                ...(avatarUrl ? { avatarUrl } : {}),
             };
         }));
     }
+    async searchMembers(input) {
+        validateSnowflake(input.guildId, "guild");
+        const query = input.query.trim();
+        if (query.length < 1 || query.length > 100)
+            throw new Error("Discord member search query is invalid");
+        if (!Number.isSafeInteger(input.limit) ||
+            input.limit < 1 ||
+            input.limit > 25)
+            throw new Error("Discord member search limit is invalid");
+        const guild = await this.client.guilds.fetch(input.guildId);
+        if (guild.id !== input.guildId)
+            throw new Error("Discord guild validation failed");
+        const members = await guild.members.search({
+            query,
+            limit: input.limit,
+            cache: false,
+        });
+        return [...members.values()].map((member) => {
+            const avatarUrl = memberAvatarUrl(member);
+            return {
+                userId: member.id,
+                displayName: member.displayName,
+                ...(avatarUrl ? { avatarUrl } : {}),
+                isBot: member.user.bot,
+            };
+        });
+    }
     async #resolveMemberGuild(input) {
         validateSnowflake(input.guildId, "guild");
         if (input.userIds.length > 50 ||
@@ -574,9 +1031,13 @@ export class DiscordResourceInspection {
         const guild = await this.client.guilds.fetch(input.guildId);
         if (guild.id !== input.guildId)
             throw new Error("Discord guild validation failed");
+        const canonicalCustom = /^custom:(\d{17,20})$/u.exec(input.emojiIdentifier);
+        const canonicalUnicode = /^unicode:(.+)$/u.exec(input.emojiIdentifier);
         const custom = customEmojiIdentifier.exec(input.emojiIdentifier);
-        if (!custom) {
-            const normalized = input.emojiIdentifier.normalize("NFKC").trim();
+        if (!custom && !canonicalCustom) {
+            const normalized = (canonicalUnicode?.[1] ?? input.emojiIdentifier)
+                .normalize("NFKC")
+                .trim();
             const valid = isSingleUnicodeEmoji(normalized);
             return {
                 guildId: guild.id,
@@ -590,7 +1051,9 @@ export class DiscordResourceInspection {
                     : {}),
             };
         }
-        const emojiId = custom[2] ?? custom[4];
+        const emojiId = canonicalCustom?.[1] ?? custom?.[2] ?? custom?.[4];
+        if (!emojiId)
+            throw new Error("Invalid bounded Discord emoji identifier");
         const emoji = await guild.emojis.fetch(emojiId).catch(() => null);
         if (!emoji)
             return {
@@ -612,7 +1075,7 @@ export class DiscordResourceInspection {
             kind: "custom",
             canonicalEmojiKey: `custom:${emoji.id}`,
             emojiId: emoji.id,
-            name: emoji.name ?? custom[1] ?? custom[3] ?? "emoji",
+            name: emoji.name ?? custom?.[1] ?? custom?.[3] ?? "emoji",
         };
     }
     async inspectChannel(input) {
@@ -634,6 +1097,7 @@ export class DiscordResourceInspection {
                 sendMessages: false,
                 addReactions: false,
                 readMessageHistory: false,
+                manageMessages: false,
             };
         const guildMatches = channel.guild.id === guild.id;
         const me = guild.members.me ?? (await guild.members.fetchMe());
@@ -659,8 +1123,198 @@ export class DiscordResourceInspection {
                 (effective?.has(PermissionFlagsBits.AddReactions) ?? false),
             readMessageHistory: guildMatches &&
                 (effective?.has(PermissionFlagsBits.ReadMessageHistory) ?? false),
+            manageMessages: guildMatches &&
+                (effective?.has(PermissionFlagsBits.ManageMessages) ?? false),
+        };
+    }
+    async inspectMessage(input) {
+        validateSnowflake(input.guildId, "guild");
+        validateSnowflake(input.channelId, "channel");
+        validateSnowflake(input.messageId, "message");
+        const guild = await this.client.guilds.fetch(input.guildId);
+        if (guild.id !== input.guildId)
+            throw new Error("Discord guild validation failed");
+        const channel = await guild.channels.fetch(input.channelId);
+        if (!channel ||
+            channel.guild.id !== guild.id ||
+            !channel.isTextBased() ||
+            channel.isDMBased()) {
+            return missingMessageInspection(input, false);
+        }
+        const message = await channel.messages
+            .fetch(input.messageId)
+            .catch((error) => {
+            if (isUnknownMessage(error))
+                return null;
+            throw error;
+        });
+        if (!message)
+            return missingMessageInspection(input, true);
+        const guildMatches = message.guildId === guild.id;
+        const channelMatches = message.channelId === channel.id;
+        return {
+            guildId: guild.id,
+            channelId: channel.id,
+            messageId: message.id,
+            exists: guildMatches && channelMatches && message.id === input.messageId,
+            guildMatches,
+            channelMatches,
+            authorUserId: message.author.id,
         };
     }
+    async inspectChannelAudience(input) {
+        validateSnowflake(input.guildId, "guild");
+        validateSnowflake(input.channelId, "channel");
+        validateBoundedRoleSet(input.roleIds, "audience");
+        const guild = await this.client.guilds.fetch(input.guildId);
+        if (guild.id !== input.guildId)
+            throw new Error("Discord guild validation failed");
+        const roles = await Promise.all(input.roleIds.map(async (roleId) => ({
+            roleId,
+            role: await guild.roles.fetch(roleId),
+        })));
+        const channel = await guild.channels.fetch(input.channelId);
+        if (!channel) {
+            return {
+                guildId: guild.id,
+                channelId: input.channelId,
+                exists: false,
+                guildMatches: false,
+                everyoneCanView: false,
+                roles: roles.map(({ roleId, role }) => ({
+                    roleId,
+                    exists: role !== null && role.guild.id === guild.id,
+                    canView: false,
+                })),
+            };
+        }
+        const guildMatches = channel.guild.id === guild.id;
+        return {
+            guildId: guild.id,
+            channelId: channel.id,
+            exists: true,
+            guildMatches,
+            everyoneCanView: guildMatches &&
+                (channel
+                    .permissionsFor(guild.roles.everyone)
+                    ?.has(PermissionFlagsBits.ViewChannel) ??
+                    false),
+            roles: roles.map(({ roleId, role }) => {
+                const exists = role !== null && role.guild.id === guild.id;
+                return {
+                    roleId,
+                    exists,
+                    canView: guildMatches &&
+                        role !== null &&
+                        role.guild.id === guild.id &&
+                        (channel
+                            .permissionsFor(role)
+                            ?.has(PermissionFlagsBits.ViewChannel) ??
+                            false),
+                };
+            }),
+        };
+    }
+    async inspectGuildChannelAudience(input) {
+        validateSnowflake(input.guildId, "guild");
+        validateBoundedRoleSet(input.roleIds, "audience");
+        const guild = await this.client.guilds.fetch(input.guildId);
+        if (guild.id !== input.guildId)
+            throw new Error("Discord guild validation failed");
+        const resolvedRoles = await Promise.all(input.roleIds.map(async (roleId) => ({
+            roleId,
+            role: await guild.roles.fetch(roleId),
+        })));
+        const missingRoleIds = resolvedRoles
+            .filter(({ role }) => role === null || role.guild.id !== guild.id)
+            .map(({ roleId }) => roleId);
+        const fetched = await guild.channels.fetch();
+        const relevant = [];
+        for (const channel of fetched.values()) {
+            if (channel &&
+                (channel.type === ChannelType.GuildText ||
+                    channel.type === ChannelType.GuildAnnouncement)) {
+                if (channel.guild.id !== guild.id)
+                    throw new Error("Discord channel guild validation failed");
+                relevant.push(channel);
+            }
+        }
+        relevant.sort((left, right) => left.id.localeCompare(right.id, "en"));
+        const truncated = relevant.length > guildChannelAudienceInspectionLimit;
+        const channels = relevant
+            .slice(0, guildChannelAudienceInspectionLimit)
+            .map((channel) => {
+            const everyoneCanView = channel
+                .permissionsFor(guild.roles.everyone)
+                ?.has(PermissionFlagsBits.ViewChannel) ?? false;
+            const visibleRoleIds = resolvedRoles
+                .filter(({ role }) => role !== null &&
+                role.guild.id === guild.id &&
+                (channel
+                    .permissionsFor(role)
+                    ?.has(PermissionFlagsBits.ViewChannel) ??
+                    false))
+                .map(({ roleId }) => roleId);
+            return {
+                channelId: channel.id,
+                type: channel.type === ChannelType.GuildText
+                    ? "guild_text"
+                    : "guild_announcement",
+                everyoneCanView,
+                visibleRoleIds,
+            };
+        })
+            .filter(({ everyoneCanView, visibleRoleIds }) => everyoneCanView || visibleRoleIds.length > 0);
+        return {
+            guildId: guild.id,
+            channels,
+            missingRoleIds,
+            truncated,
+        };
+    }
+    async seedMessageReaction(input) {
+        validateSnowflake(input.guildId, "guild");
+        validateSnowflake(input.channelId, "channel");
+        validateSnowflake(input.messageId, "message");
+        const guild = await this.client.guilds.fetch(input.guildId);
+        if (guild.id !== input.guildId)
+            throw new Error("Discord guild validation failed");
+        const channel = await guild.channels.fetch(input.channelId);
+        if (!channel ||
+            channel.guild.id !== guild.id ||
+            !channel.isTextBased() ||
+            channel.isDMBased()) {
+            throw new Error("Discord reaction message channel is unavailable");
+        }
+        const message = await channel.messages.fetch(input.messageId);
+        if (message.id !== input.messageId ||
+            message.guildId !== guild.id ||
+            message.channelId !== channel.id) {
+            throw new Error("Discord reaction message validation failed");
+        }
+        const emoji = await this.inspectEmoji({
+            guildId: guild.id,
+            emojiIdentifier: input.emojiIdentifier,
+        });
+        if (!emoji.exists || !emoji.guildMatches || !emoji.usable) {
+            throw new Error("Discord reaction emoji is unavailable");
+        }
+        const cacheKey = emoji.kind === "custom" ? emoji.emojiId : (emoji.name ?? "");
+        if (message.reactions.cache.get(cacheKey)?.me)
+            return { added: false };
+        const resolvedEmoji = emoji.kind === "custom"
+            ? await guild.emojis.fetch(emoji.emojiId)
+            : emoji.name;
+        if (!resolvedEmoji)
+            throw new Error("Discord reaction emoji is unavailable");
+        await message.react(resolvedEmoji);
+        return { added: true };
+    }
+}
+function memberAvatarUrl(member) {
+    return member && typeof member.displayAvatarURL === "function"
+        ? member.displayAvatarURL({ extension: "webp", size: 64 })
+        : "";
 }
 async function fetchSafeRole(guild, roleId) {
     validateSnowflake(roleId, "role");
@@ -704,6 +1358,24 @@ function missingRoleInspection(input, hierarchy) {
         dangerousPermissionNames: [],
     };
 }
+function missingMessageInspection(input, channelMatches) {
+    return {
+        ...input,
+        exists: false,
+        guildMatches: channelMatches,
+        channelMatches,
+    };
+}
+function validateEnforcementMetadata(input) {
+    validateSnowflake(input.guildId, "guild");
+    validateSnowflake(input.memberUserId, "member");
+    if (input.moduleId.length > 100 || !moduleIdentifier.test(input.moduleId))
+        throw new Error("Member enforcement requires a valid Helyx module ID");
+    if (input.reason.trim().length === 0 ||
+        input.reason.length > 400 ||
+        /[\r\n]/u.test(input.reason))
+        throw new Error("Member enforcement requires a bounded audit reason");
+}
 function validateMutationMetadata(input) {
     validateSnowflake(input.guildId, "guild");
     validateSnowflake(input.memberUserId, "member");
@@ -716,6 +1388,22 @@ function validateMutationMetadata(input) {
         /[\r\n]/u.test(input.reason))
         throw new Error("Role mutation requires a bounded audit reason");
 }
+function validateRoleCreationMetadata(input) {
+    validateSnowflake(input.guildId, "guild");
+    if (input.name.trim() !== input.name ||
+        input.name.length < 1 ||
+        input.name.length > 100 ||
+        /[\r\n\0]/u.test(input.name) ||
+        input.name.toLowerCase() === "@everyone" ||
+        input.name.toLowerCase() === "@here")
+        throw new Error("Role creation requires a safe name from 1 to 100 characters");
+    if (input.moduleId.length > 100 || !moduleIdentifier.test(input.moduleId))
+        throw new Error("Role creation requires a valid Helyx module ID");
+    if (input.reason.trim().length === 0 ||
+        input.reason.length > 400 ||
+        /[\r\n]/u.test(input.reason))
+        throw new Error("Role creation requires a bounded audit reason");
+}
 async function fetchExactMember(guild, memberUserId, label) {
     validateSnowflake(memberUserId, label);
     const member = await guild.members.fetch(memberUserId);
@@ -729,6 +1417,18 @@ function isUnknownMember(error) {
         "code" in error &&
         error.code === RESTJSONErrorCodes.UnknownMember);
 }
+function isUnknownMessage(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === RESTJSONErrorCodes.UnknownMessage);
+}
+function isClosedDirectMessage(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === RESTJSONErrorCodes.CannotSendMessagesToThisUser);
+}
 function validateBoundedRoleSet(roleIds, label) {
     if (roleIds.length > 100 || new Set(roleIds).size !== roleIds.length)
         throw new Error(`${label} role IDs must be unique and bounded`);