@helyx/bot 1.1.0 → 1.2.0

package/dist/discord-auto-moderation-service.js

@@ -0,0 +1,425 @@
+import { AutoModerationActionType, AutoModerationRuleEventType, AutoModerationRuleKeywordPresetType, AutoModerationRuleTriggerType, DiscordAPIError, PermissionFlagsBits, } from "discord.js";
+const SNOWFLAKE_PATTERN = /^\d{17,20}$/u;
+const OPERATION_KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$/u;
+const MODULE_ID_PATTERN = /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)+$/u;
+const MAX_RULE_NAME_CHARACTERS = 100;
+const MAX_KEYWORDS = 1_000;
+const MAX_KEYWORD_CHARACTERS = 60;
+const MAX_REGEX_PATTERNS = 10;
+const MAX_REGEX_CHARACTERS = 260;
+const MAX_KEYWORD_ALLOW_LIST = 100;
+const MAX_PRESET_ALLOW_LIST = 1_000;
+const MAX_EXEMPT_ROLES = 20;
+const MAX_EXEMPT_CHANNELS = 50;
+const MAX_ACTIONS = 3;
+const MAX_CUSTOM_MESSAGE_CHARACTERS = 150;
+const MAX_TIMEOUT_SECONDS = 2_419_200;
+const MAX_RULES_BY_TRIGGER = Object.freeze({
+    keyword: 6,
+    spam: 1,
+    keyword_preset: 1,
+    mention_spam: 1,
+});
+/** Discord REST adapter scoped to guilds owned by this client/shard. */
+export class DiscordAutoModerationAdapter {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async list(input) {
+        const guild = this.#ownedGuild(input.guildId);
+        if (!guild)
+            return [];
+        this.#requireManageGuild(guild);
+        const rules = await guild.autoModerationRules.fetch();
+        return [...rules.values()].map(toRuleSnapshot);
+    }
+    async read(input) {
+        validateSnowflake(input.ruleId, "ruleId");
+        const guild = this.#ownedGuild(input.guildId);
+        if (!guild)
+            return null;
+        this.#requireManageGuild(guild);
+        try {
+            return toRuleSnapshot(await guild.autoModerationRules.fetch(input.ruleId));
+        }
+        catch (error) {
+            if (isDiscordStatus(error, 404))
+                return null;
+            throw error;
+        }
+    }
+    async create(input) {
+        validateMutationMetadata(input);
+        validateRule(input.rule);
+        const guild = this.#ownedGuild(input.guildId);
+        if (!guild)
+            return failed("guild_not_owned");
+        const permissionFailure = this.#permissionFailure(guild, input.rule);
+        if (permissionFailure)
+            return permissionFailure;
+        const rules = await guild.autoModerationRules.fetch().catch(() => null);
+        if (!rules)
+            return failed("rule_inspection_failed");
+        const matching = [...rules.values()].find((rule) => rule.name === input.rule.name &&
+            sameRule(toRuleSnapshot(rule), input.rule));
+        if (matching)
+            return { outcome: "already_applied", rule: toRuleSnapshot(matching) };
+        const triggerCount = [...rules.values()].filter((rule) => triggerType(rule.triggerType) === input.rule.trigger.type).length;
+        if (triggerCount >= MAX_RULES_BY_TRIGGER[input.rule.trigger.type])
+            return { outcome: "capacity_exceeded", safeCode: "trigger_capacity" };
+        if (!(await safelyRevalidate(() => input.revalidate())))
+            return failed("revalidation_rejected");
+        try {
+            const created = await guild.autoModerationRules.create(toCreateOptions(input.rule, auditReason(input)));
+            return { outcome: "succeeded", rule: toRuleSnapshot(created) };
+        }
+        catch (error) {
+            return mutationFailure(error);
+        }
+    }
+    async update(input) {
+        validateMutationMetadata(input);
+        validateSnowflake(input.ruleId, "ruleId");
+        validateRule(input.rule);
+        const guild = this.#ownedGuild(input.guildId);
+        if (!guild)
+            return failed("guild_not_owned");
+        const permissionFailure = this.#permissionFailure(guild, input.rule);
+        if (permissionFailure)
+            return permissionFailure;
+        let existing;
+        try {
+            existing = await guild.autoModerationRules.fetch(input.ruleId);
+        }
+        catch (error) {
+            return isDiscordStatus(error, 404)
+                ? { outcome: "already_absent" }
+                : mutationFailure(error);
+        }
+        if (triggerType(existing.triggerType) !== input.rule.trigger.type)
+            return { outcome: "invalid_rule", safeCode: "trigger_type_immutable" };
+        if (sameRule(toRuleSnapshot(existing), input.rule))
+            return { outcome: "already_applied", rule: toRuleSnapshot(existing) };
+        if (!(await safelyRevalidate(() => input.revalidate())))
+            return failed("revalidation_rejected");
+        try {
+            const { triggerType: _triggerType, ...editOptions } = toCreateOptions(input.rule, auditReason(input));
+            void _triggerType;
+            const updated = await guild.autoModerationRules.edit(input.ruleId, editOptions);
+            return { outcome: "succeeded", rule: toRuleSnapshot(updated) };
+        }
+        catch (error) {
+            return mutationFailure(error);
+        }
+    }
+    async delete(input) {
+        validateMutationMetadata(input);
+        validateSnowflake(input.ruleId, "ruleId");
+        const guild = this.#ownedGuild(input.guildId);
+        if (!guild)
+            return failed("guild_not_owned");
+        if (!this.#hasPermission(guild, PermissionFlagsBits.ManageGuild))
+            return { outcome: "missing_permission", safeCode: "manage_guild" };
+        const existing = await this.read({
+            guildId: input.guildId,
+            ruleId: input.ruleId,
+        }).catch(() => null);
+        if (!existing)
+            return { outcome: "already_absent" };
+        if (!(await safelyRevalidate(() => input.revalidate())))
+            return failed("revalidation_rejected");
+        try {
+            await guild.autoModerationRules.delete(input.ruleId, auditReason(input));
+            return { outcome: "succeeded", rule: null };
+        }
+        catch (error) {
+            return isDiscordStatus(error, 404)
+                ? { outcome: "already_absent" }
+                : mutationFailure(error);
+        }
+    }
+    #ownedGuild(guildId) {
+        validateSnowflake(guildId, "guildId");
+        return this.client.guilds.cache.get(guildId) ?? null;
+    }
+    #hasPermission(guild, permission) {
+        return Boolean(guild.members.me?.permissions.has(permission));
+    }
+    #requireManageGuild(guild) {
+        if (!this.#hasPermission(guild, PermissionFlagsBits.ManageGuild))
+            throw new Error("Discord Auto Moderation inspection is unavailable");
+    }
+    #permissionFailure(guild, rule) {
+        if (!this.#hasPermission(guild, PermissionFlagsBits.ManageGuild))
+            return { outcome: "missing_permission", safeCode: "manage_guild" };
+        if (rule.actions.some(({ type }) => type === "timeout") &&
+            !this.#hasPermission(guild, PermissionFlagsBits.ModerateMembers))
+            return { outcome: "missing_permission", safeCode: "moderate_members" };
+        return null;
+    }
+}
+export function toRuleSnapshot(rule) {
+    return {
+        guildId: rule.guild.id,
+        ruleId: rule.id,
+        creatorUserId: rule.creatorId,
+        name: rule.name,
+        enabled: rule.enabled,
+        eventType: "message_send",
+        trigger: fromDiscordTrigger(rule),
+        actions: rule.actions.map(fromDiscordAction),
+        exemptRoleIds: [...rule.exemptRoles.keys()].sort(),
+        exemptChannelIds: [...rule.exemptChannels.keys()].sort(),
+    };
+}
+export function fromDiscordAction(action) {
+    if (action.type === AutoModerationActionType.BlockMessage)
+        return {
+            type: "block_message",
+            ...(action.metadata.customMessage
+                ? { customMessage: action.metadata.customMessage }
+                : {}),
+        };
+    if (action.type === AutoModerationActionType.SendAlertMessage &&
+        action.metadata.channelId)
+        return { type: "send_alert_message", channelId: action.metadata.channelId };
+    if (action.type === AutoModerationActionType.Timeout &&
+        action.metadata.durationSeconds)
+        return {
+            type: "timeout",
+            durationSeconds: action.metadata.durationSeconds,
+        };
+    throw new Error("Discord Auto Moderation action is unsupported");
+}
+function fromDiscordTrigger(rule) {
+    const metadata = rule.triggerMetadata;
+    if (rule.triggerType === AutoModerationRuleTriggerType.Keyword)
+        return {
+            type: "keyword",
+            keywordFilter: [...metadata.keywordFilter],
+            regexPatterns: [...metadata.regexPatterns],
+            allowList: [...metadata.allowList],
+        };
+    if (rule.triggerType === AutoModerationRuleTriggerType.Spam)
+        return { type: "spam" };
+    if (rule.triggerType === AutoModerationRuleTriggerType.KeywordPreset)
+        return {
+            type: "keyword_preset",
+            presets: metadata.presets.map(fromPreset),
+            allowList: [...metadata.allowList],
+        };
+    if (rule.triggerType === AutoModerationRuleTriggerType.MentionSpam)
+        return {
+            type: "mention_spam",
+            mentionTotalLimit: metadata.mentionTotalLimit ?? 0,
+            mentionRaidProtectionEnabled: metadata.mentionRaidProtectionEnabled,
+        };
+    throw new Error("Discord Auto Moderation trigger is unsupported");
+}
+function toCreateOptions(rule, reason) {
+    const triggerMetadata = toDiscordTriggerMetadata(rule.trigger);
+    return {
+        name: rule.name,
+        eventType: AutoModerationRuleEventType.MessageSend,
+        triggerType: toDiscordTriggerType(rule.trigger.type),
+        ...(triggerMetadata ? { triggerMetadata } : {}),
+        actions: rule.actions.map(toDiscordAction),
+        enabled: rule.enabled,
+        exemptRoles: rule.exemptRoleIds,
+        exemptChannels: rule.exemptChannelIds,
+        reason,
+    };
+}
+function toDiscordTriggerMetadata(trigger) {
+    if (trigger.type === "keyword")
+        return {
+            keywordFilter: trigger.keywordFilter,
+            regexPatterns: trigger.regexPatterns,
+            allowList: trigger.allowList,
+        };
+    if (trigger.type === "keyword_preset")
+        return {
+            presets: trigger.presets.map(toPreset),
+            allowList: trigger.allowList,
+        };
+    if (trigger.type === "mention_spam")
+        return {
+            mentionTotalLimit: trigger.mentionTotalLimit,
+            mentionRaidProtectionEnabled: trigger.mentionRaidProtectionEnabled,
+        };
+    return undefined;
+}
+function toDiscordAction(action) {
+    if (action.type === "block_message")
+        return {
+            type: AutoModerationActionType.BlockMessage,
+            ...(action.customMessage
+                ? { metadata: { customMessage: action.customMessage } }
+                : {}),
+        };
+    if (action.type === "send_alert_message")
+        return {
+            type: AutoModerationActionType.SendAlertMessage,
+            metadata: { channel: action.channelId },
+        };
+    return {
+        type: AutoModerationActionType.Timeout,
+        metadata: { durationSeconds: action.durationSeconds },
+    };
+}
+function toDiscordTriggerType(type) {
+    if (type === "keyword")
+        return AutoModerationRuleTriggerType.Keyword;
+    if (type === "spam")
+        return AutoModerationRuleTriggerType.Spam;
+    if (type === "keyword_preset")
+        return AutoModerationRuleTriggerType.KeywordPreset;
+    return AutoModerationRuleTriggerType.MentionSpam;
+}
+function triggerType(type) {
+    if (type === AutoModerationRuleTriggerType.Keyword)
+        return "keyword";
+    if (type === AutoModerationRuleTriggerType.Spam)
+        return "spam";
+    if (type === AutoModerationRuleTriggerType.KeywordPreset)
+        return "keyword_preset";
+    if (type === AutoModerationRuleTriggerType.MentionSpam)
+        return "mention_spam";
+    throw new Error("Discord Auto Moderation trigger is unsupported");
+}
+function toPreset(preset) {
+    if (preset === "profanity")
+        return AutoModerationRuleKeywordPresetType.Profanity;
+    if (preset === "sexual_content")
+        return AutoModerationRuleKeywordPresetType.SexualContent;
+    return AutoModerationRuleKeywordPresetType.Slurs;
+}
+function fromPreset(preset) {
+    if (preset === AutoModerationRuleKeywordPresetType.Profanity)
+        return "profanity";
+    if (preset === AutoModerationRuleKeywordPresetType.SexualContent)
+        return "sexual_content";
+    if (preset === AutoModerationRuleKeywordPresetType.Slurs)
+        return "slurs";
+    throw new Error("Discord Auto Moderation preset is unsupported");
+}
+function validateRule(rule) {
+    if (rule.eventType !== "message_send" ||
+        rule.name.trim().length < 1 ||
+        rule.name.length > MAX_RULE_NAME_CHARACTERS ||
+        rule.actions.length < 1 ||
+        rule.actions.length > MAX_ACTIONS ||
+        rule.exemptRoleIds.length > MAX_EXEMPT_ROLES ||
+        rule.exemptChannelIds.length > MAX_EXEMPT_CHANNELS ||
+        new Set(rule.exemptRoleIds).size !== rule.exemptRoleIds.length ||
+        new Set(rule.exemptChannelIds).size !== rule.exemptChannelIds.length)
+        throw new Error("Discord Auto Moderation rule is invalid");
+    rule.exemptRoleIds.forEach((id) => validateSnowflake(id, "exemptRoleId"));
+    rule.exemptChannelIds.forEach((id) => validateSnowflake(id, "exemptChannelId"));
+    validateTrigger(rule.trigger);
+    validateActions(rule.actions, rule.trigger.type);
+}
+function validateTrigger(trigger) {
+    if (trigger.type === "keyword") {
+        validateStrings(trigger.keywordFilter, MAX_KEYWORDS, MAX_KEYWORD_CHARACTERS);
+        validateStrings(trigger.regexPatterns, MAX_REGEX_PATTERNS, MAX_REGEX_CHARACTERS);
+        validateStrings(trigger.allowList, MAX_KEYWORD_ALLOW_LIST, MAX_KEYWORD_CHARACTERS);
+        return;
+    }
+    if (trigger.type === "keyword_preset") {
+        if (trigger.presets.length < 1 ||
+            trigger.presets.length > 3 ||
+            new Set(trigger.presets).size !== trigger.presets.length)
+            throw new Error("Discord Auto Moderation presets are invalid");
+        validateStrings(trigger.allowList, MAX_PRESET_ALLOW_LIST, MAX_KEYWORD_CHARACTERS);
+        return;
+    }
+    if (trigger.type === "mention_spam" &&
+        (!Number.isInteger(trigger.mentionTotalLimit) ||
+            trigger.mentionTotalLimit < 1 ||
+            trigger.mentionTotalLimit > 50))
+        throw new Error("Discord Auto Moderation mention limit is invalid");
+}
+function validateActions(actions, triggerType) {
+    if (new Set(actions.map(({ type }) => type)).size !== actions.length)
+        throw new Error("Discord Auto Moderation actions must be unique");
+    for (const action of actions) {
+        if (action.type === "block_message" &&
+            action.customMessage !== undefined &&
+            (action.customMessage.trim().length < 1 ||
+                action.customMessage.length > MAX_CUSTOM_MESSAGE_CHARACTERS))
+            throw new Error("Discord Auto Moderation block message is invalid");
+        if (action.type === "send_alert_message")
+            validateSnowflake(action.channelId, "alertChannelId");
+        if (action.type === "timeout" &&
+            (triggerType === "spam" ||
+                triggerType === "keyword_preset" ||
+                !Number.isInteger(action.durationSeconds) ||
+                action.durationSeconds < 1 ||
+                action.durationSeconds > MAX_TIMEOUT_SECONDS))
+            throw new Error("Discord Auto Moderation timeout is invalid");
+    }
+}
+function validateStrings(values, maximumItems, maximumCharacters) {
+    if (values.length > maximumItems ||
+        new Set(values).size !== values.length ||
+        values.some((value) => value.length < 1 || value.length > maximumCharacters))
+        throw new Error("Discord Auto Moderation trigger values are invalid");
+}
+function validateMutationMetadata(input) {
+    validateSnowflake(input.guildId, "guildId");
+    if (!MODULE_ID_PATTERN.test(input.callerModuleId) ||
+        !OPERATION_KEY_PATTERN.test(input.operationKey))
+        throw new Error("Discord Auto Moderation mutation metadata is invalid");
+}
+function validateSnowflake(value, name) {
+    if (!SNOWFLAKE_PATTERN.test(value))
+        throw new Error(`${name} is invalid`);
+}
+function sameRule(snapshot, definition) {
+    return (JSON.stringify({
+        name: snapshot.name,
+        enabled: snapshot.enabled,
+        eventType: snapshot.eventType,
+        trigger: snapshot.trigger,
+        actions: snapshot.actions,
+        exemptRoleIds: [...snapshot.exemptRoleIds].sort(),
+        exemptChannelIds: [...snapshot.exemptChannelIds].sort(),
+    }) ===
+        JSON.stringify({
+            ...definition,
+            exemptRoleIds: [...definition.exemptRoleIds].sort(),
+            exemptChannelIds: [...definition.exemptChannelIds].sort(),
+        }));
+}
+function auditReason(input) {
+    return `Helyx ${input.callerModuleId} ${input.operationKey}`.slice(0, 512);
+}
+async function safelyRevalidate(revalidate) {
+    try {
+        return await revalidate();
+    }
+    catch {
+        return false;
+    }
+}
+function mutationFailure(error) {
+    if (isDiscordStatus(error, 403))
+        return { outcome: "missing_permission", safeCode: "discord_forbidden" };
+    if (isDiscordStatus(error, 400))
+        return { outcome: "invalid_rule", safeCode: "discord_invalid_rule" };
+    if (error instanceof DiscordAPIError)
+        return {
+            outcome: "failed",
+            safeCode: `discord_${error.code}`.slice(0, 80),
+        };
+    return { outcome: "ambiguous", safeCode: "discord_transport_unknown" };
+}
+function failed(safeCode) {
+    return { outcome: "failed", safeCode };
+}
+function isDiscordStatus(error, status) {
+    return error instanceof DiscordAPIError && error.status === status;
+}
+//# sourceMappingURL=discord-auto-moderation-service.js.map

package/dist/discord-guild-health.d.ts

@@ -163,8 +163,8 @@ export declare class DiscordGuildHealthInspection implements DiscordGuildHealthI
             resourceValidationValid: boolean | null;
             activationValid: boolean | null;
             catalogueMatches: boolean;
-            requiredCapabilities: readonly ("message-content" | "guild-members")[];
-            missingCapabilities: ("message-content" | "guild-members")[];
+            requiredCapabilities: readonly ("guild-members" | "message-content")[];
+            missingCapabilities: ("guild-members" | "message-content")[];
             missingPermissions: string[];
             healthStatus: "healthy" | "degraded" | "unhealthy";
             healthMessage: string | null;

package/dist/discord-member-enforcement-service.d.ts

@@ -0,0 +1,26 @@
+import type { BanStateInspection, MemberEnforcementInspection, MemberEnforcementService, ModerationMemberEnforcementService } from "@helyx/sdk";
+import { type Client } from "discord.js";
+/** Extended Moderation adapter, leaving the legacy enforcement class unchanged. */
+export declare class DiscordModerationMemberEnforcementAdapter implements ModerationMemberEnforcementService {
+    #private;
+    private readonly client;
+    constructor(client: Client);
+    kick(input: Parameters<MemberEnforcementService["kick"]>[0]): ReturnType<MemberEnforcementService["kick"]>;
+    ban(input: Parameters<MemberEnforcementService["ban"]>[0]): ReturnType<MemberEnforcementService["ban"]>;
+    inspectMember(input: {
+        guildId: string;
+        memberUserId: string;
+        actorUserId?: string;
+    }): Promise<MemberEnforcementInspection>;
+    inspectBan(input: {
+        guildId: string;
+        userId: string;
+    }): Promise<BanStateInspection>;
+    kickMember(input: Parameters<ModerationMemberEnforcementService["kickMember"]>[0]): ReturnType<ModerationMemberEnforcementService["kickMember"]>;
+    banMember(input: Parameters<ModerationMemberEnforcementService["banMember"]>[0]): ReturnType<ModerationMemberEnforcementService["banMember"]>;
+    timeout(input: Parameters<ModerationMemberEnforcementService["timeout"]>[0]): ReturnType<ModerationMemberEnforcementService["timeout"]>;
+    removeTimeout(input: Parameters<ModerationMemberEnforcementService["removeTimeout"]>[0]): ReturnType<ModerationMemberEnforcementService["removeTimeout"]>;
+    unban(input: Parameters<ModerationMemberEnforcementService["unban"]>[0]): ReturnType<ModerationMemberEnforcementService["unban"]>;
+    removeConfiguredRoles(input: Parameters<ModerationMemberEnforcementService["removeConfiguredRoles"]>[0]): ReturnType<ModerationMemberEnforcementService["removeConfiguredRoles"]>;
+}
+//# sourceMappingURL=discord-member-enforcement-service.d.ts.map