@helyx/module-automod 1.0.1

package/dist/resource-presentation.js

@@ -0,0 +1,111 @@
+export function previewMessage(draft) {
+    const disclosures = draft.alertChannelId
+        ? "Discord alerts may include the triggering message content in the selected channel."
+        : "Helyx stores structural receipts only; it does not store matched content.";
+    return {
+        embeds: [
+            {
+                title: `Auto Moderation preview - ${draft.name}`,
+                description: `${filterSummary(draft)}\n\n${disclosures}`,
+                fields: [
+                    { name: "Category", value: draft.category, inline: true },
+                    {
+                        name: "Native actions",
+                        value: nativeActionSummary(draft),
+                        inline: true,
+                    },
+                    {
+                        name: "Repeat offender",
+                        value: repeatSummary(draft),
+                        inline: false,
+                    },
+                ],
+            },
+        ],
+    };
+}
+export function ruleSummary(rule) {
+    return {
+        id: rule.ruleId,
+        revision: rule.revision,
+        status: rule.status,
+        title: rule.name,
+        description: `${rule.category} - ${rule.kind.replaceAll("_", " ")}`,
+        attributes: {
+            filter: filterSummary(rule.draft),
+            action: nativeActionSummary(rule.draft),
+            moderationThread: rule.draft.openViolationThread ? "Open" : "Off",
+            ignoredRoles: rule.draft.ignoredRoleIds,
+            repeatOffender: repeatSummary(rule.draft),
+        },
+        updatedAt: rule.updatedAt.toISOString(),
+    };
+}
+export function ruleDetail(rule) {
+    return {
+        ...ruleSummary(rule),
+        value: {
+            name: rule.draft.name,
+            category: rule.draft.category,
+            ruleKind: rule.draft.kind,
+            keywordFilter: rule.draft.keywordFilter.join("\n"),
+            regexPatterns: rule.draft.regexPatterns.join("\n"),
+            allowList: rule.draft.allowList.join("\n"),
+            enhancedNormalisedMatching: rule.draft.enhancedNormalisedMatching !== false,
+            enhancedFuzzyMatching: rule.draft.enhancedFuzzyMatching === true,
+            presetProfanity: rule.draft.presets.includes("profanity"),
+            presetSexualContent: rule.draft.presets.includes("sexual_content"),
+            presetSlurs: rule.draft.presets.includes("slurs"),
+            mentionTotalLimit: rule.draft.mentionTotalLimit,
+            mentionRaidProtectionEnabled: rule.draft.mentionRaidProtectionEnabled,
+            blockMessage: rule.draft.blockMessage,
+            blockExplanation: rule.draft.blockExplanation,
+            alertChannelId: rule.draft.alertChannelId,
+            nativeTimeoutSeconds: String(rule.draft.nativeTimeoutSeconds ?? 0),
+            ignoredRoleIds: rule.draft.ignoredRoleIds,
+            ignoredChannelIds: rule.draft.ignoredChannelIds,
+            openViolationThread: rule.draft.openViolationThread,
+            ...actionValues("first", rule.draft.actionPolicy.first),
+            ...actionValues("second", rule.draft.actionPolicy.second),
+            ...actionValues("third", rule.draft.actionPolicy.thirdAndLater),
+            nativeRuleId: rule.nativeRuleId,
+            configurationRevision: rule.configurationRevision,
+        },
+    };
+}
+function actionValues(prefix, action) {
+    return {
+        [`${prefix}Action`]: action.type,
+        [`${prefix}TimeoutSeconds`]: String(action.type === "timeout" ? action.durationSeconds : 300),
+        [`${prefix}BanDeleteMessageSeconds`]: String(action.type === "ban" ? action.deleteMessageSeconds : 0),
+        [`${prefix}DemoteRoleIds`]: action.type === "demote" ? action.roleIds : [],
+    };
+}
+function filterSummary(draft) {
+    if (draft.kind === "keyword")
+        return `${draft.keywordFilter.length} keyword/phrase entries - ${draft.regexPatterns.length} regex patterns`;
+    if (draft.kind === "keyword_preset")
+        return draft.presets.join(", ") || "No preset selected";
+    if (draft.kind === "mention_spam")
+        return `${draft.mentionTotalLimit} mentions per message`;
+    return "Discord generic spam detection";
+}
+function nativeActionSummary(draft) {
+    return ([
+        draft.blockMessage ? "Block" : null,
+        draft.alertChannelId ? "Alert" : null,
+        draft.nativeTimeoutSeconds ? `Mute ${draft.nativeTimeoutSeconds}s` : null,
+    ]
+        .filter(Boolean)
+        .join(" - ") || "None");
+}
+function repeatSummary(draft) {
+    return [
+        draft.actionPolicy.first.type,
+        draft.actionPolicy.second.type,
+        draft.actionPolicy.thirdAndLater.type,
+    ]
+        .map((value) => value.replaceAll("_", " "))
+        .join(" -> ");
+}
+//# sourceMappingURL=resource-presentation.js.map

package/dist/resource-validation.d.ts

@@ -0,0 +1,6 @@
+import { type ServiceAccess } from "@helyx/sdk";
+import type { AutoModerationRuleDraft } from "./domain.js";
+import type { AutoModerationRepository } from "./repository.js";
+export declare function validateRuleReferences(services: ServiceAccess, guildId: string, draft: AutoModerationRuleDraft): Promise<void>;
+export declare function validateSingletonKind(repository: AutoModerationRepository, guildId: string, kind: AutoModerationRuleDraft["kind"], exceptRuleId?: string): Promise<void>;
+//# sourceMappingURL=resource-validation.d.ts.map

package/dist/resource-validation.js

@@ -0,0 +1,80 @@
+import { DashboardActionValidationError, HELYX_SERVICE_NAMES, } from "@helyx/sdk";
+import { AUTOMOD_LIMITS } from "./constants.js";
+import { currentConfiguration } from "./publication-support.js";
+export async function validateRuleReferences(services, guildId, draft) {
+    const configuration = await currentConfiguration(services, guildId);
+    const violationRole = await violationAccessRole(services, guildId);
+    const ignoredRoles = [
+        ...new Set([
+            ...draft.ignoredRoleIds,
+            ...configuration.value.defaultExemptRoleIds,
+        ]),
+    ];
+    const demotionRoles = [
+        ...new Set([
+            draft.actionPolicy.first,
+            draft.actionPolicy.second,
+            draft.actionPolicy.thirdAndLater,
+        ].flatMap((action) => action.type === "demote" ? action.roleIds : [])),
+    ];
+    if (violationRole &&
+        (ignoredRoles.includes(violationRole) ||
+            demotionRoles.includes(violationRole)))
+        throw new DashboardActionValidationError("The violation-access role cannot be ignored or removed by Auto Moderation.");
+    if (!services.has(HELYX_SERVICE_NAMES.discordResources))
+        throw new DashboardActionValidationError("Discord role and channel validation is temporarily unavailable.");
+    const inspection = services.get(HELYX_SERVICE_NAMES.discordResources);
+    await Promise.all(ignoredRoles.map(async (roleId) => {
+        const role = await inspection.inspectRole({ guildId, roleId });
+        if (!role.exists || !role.guildMatches)
+            throw new DashboardActionValidationError("An ignored role is missing from this server.");
+    }));
+    await Promise.all(demotionRoles.map(async (roleId) => {
+        const role = await inspection.inspectRole({ guildId, roleId });
+        if (!role.exists || !role.guildMatches || !role.assignable)
+            throw new DashboardActionValidationError("A demotion role cannot be safely managed by Helyx.");
+    }));
+    const alertChannelId = draft.alertChannelId ?? configuration.value.defaultNativeAlertChannelId;
+    const ignoredChannels = [
+        ...new Set([
+            ...draft.ignoredChannelIds,
+            ...configuration.value.defaultExemptChannelIds,
+        ]),
+    ];
+    await Promise.all(ignoredChannels.map(async (channelId) => {
+        const channel = await inspection.inspectChannel({ guildId, channelId });
+        if (!channel.exists || !channel.guildMatches)
+            throw new DashboardActionValidationError("An ignored channel is missing from this server.");
+    }));
+    if (alertChannelId) {
+        const channel = await inspection.inspectChannel({
+            guildId,
+            channelId: alertChannelId,
+        });
+        if (!channel.exists ||
+            !channel.guildMatches ||
+            !["guild_text", "guild_announcement"].includes(channel.type))
+            throw new DashboardActionValidationError("The Discord alert channel must be a text or announcement channel in this server.");
+    }
+}
+export async function validateSingletonKind(repository, guildId, kind, exceptRuleId) {
+    if (kind === "keyword")
+        return;
+    const page = await repository.listRules({
+        guildId,
+        limit: AUTOMOD_LIMITS.rulePageSize,
+    });
+    if (page.items.some((rule) => rule.kind === kind && rule.ruleId !== exceptRuleId))
+        throw new DashboardActionValidationError(`Only one ${kind.replaceAll("_", " ")} rule can be owned by Helyx.`);
+}
+async function violationAccessRole(services, guildId) {
+    if (!services.has(HELYX_SERVICE_NAMES.configuration))
+        return null;
+    const moderation = await services
+        .get(HELYX_SERVICE_NAMES.configuration)
+        .get(guildId, "helyx.moderation");
+    return typeof moderation?.value.violationAccessRoleId === "string"
+        ? moderation.value.violationAccessRoleId
+        : null;
+}
+//# sourceMappingURL=resource-validation.js.map

package/dist/resources.d.ts

@@ -0,0 +1,4 @@
+import { type ModuleManagedResource } from "@helyx/sdk";
+import type { AutoModerationPublicationService } from "./publication.js";
+export declare function createAutoModerationRulesResource(publication: AutoModerationPublicationService): ModuleManagedResource;
+//# sourceMappingURL=resources.d.ts.map

package/dist/resources.js

@@ -0,0 +1,319 @@
+import { AUTOMOD_TIMEOUT_SECONDS, DashboardActionValidationError, HELYX_SERVICE_NAMES, } from "@helyx/sdk";
+import { AUTOMOD_LIMITS, AUTOMOD_MODULE_ID, AUTOMOD_PERMISSION_IDS, } from "./constants.js";
+import { parseRuleDraft, canonicalRuleFingerprint, nativeRuleOwnershipMarker, } from "./domain.js";
+import { currentConfiguration } from "./publication.js";
+import { cursorBinding, decodeCursor, encodeCursor, } from "./resource-cursor.js";
+import { previewMessage, ruleDetail, ruleSummary, } from "./resource-presentation.js";
+import { validateRuleReferences, validateSingletonKind, } from "./resource-validation.js";
+import { canonicalTermKey, parseEnhancedTermImport } from "./engine/index.js";
+import { AutoModerationRepository, } from "./repository.js";
+export function createAutoModerationRulesResource(publication) {
+    return {
+        id: "automod-rules",
+        availableWhileDisabled: true,
+        async list(context, input) {
+            const binding = cursorBinding(context.guildId, input.search, input.filters);
+            const cursor = decodeCursor(input.cursor, binding);
+            const page = await publication.repository(context.services).listRules({
+                guildId: context.guildId,
+                limit: input.limit,
+                ...(cursor ? { cursor } : {}),
+                ...(input.search ? { search: input.search.trim() } : {}),
+                ...(validStatus(input.filters?.status)
+                    ? { status: input.filters.status }
+                    : {}),
+            });
+            return {
+                items: page.items.map(ruleSummary),
+                ...(page.nextCursor
+                    ? { nextCursor: encodeCursor(page.nextCursor, binding) }
+                    : {}),
+            };
+        },
+        async read(context, resourceId) {
+            const rule = await publication
+                .repository(context.services)
+                .findRule(context.guildId, resourceId);
+            return rule ? ruleDetail(rule) : null;
+        },
+        async preview(context, value) {
+            const draft = validatedDraft(value);
+            await validateRuleReferences(context.services, context.guildId, draft);
+            return previewMessage(draft);
+        },
+        import(_context, input) {
+            let result;
+            try {
+                result = parseEnhancedTermImport(input.content, {
+                    maximumBytes: AUTOMOD_LIMITS.importBytes,
+                    maximumTerms: AUTOMOD_LIMITS.termsPerRule,
+                    maximumTermCharacters: AUTOMOD_LIMITS.termCharacters,
+                });
+            }
+            catch (error) {
+                throw new DashboardActionValidationError(error instanceof Error ? error.message : "The import is invalid.");
+            }
+            return Promise.resolve({
+                value: { keywordFilter: result.accepted.join("\n") },
+                preview: {
+                    accepted: result.accepted.length,
+                    rejected: result.rejected.length,
+                    duplicateCount: result.duplicateCount,
+                    rowErrors: result.rejected.slice(0, 100),
+                },
+            });
+        },
+        async create(context, value, intent = "publish") {
+            if (intent !== "publish")
+                throw new DashboardActionValidationError("Save the rule to validate and apply it to Discord.");
+            const draft = validatedDraft(value);
+            await validateRuleReferences(context.services, context.guildId, draft);
+            await validateSingletonKind(publication.repository(context.services), context.guildId, draft.kind);
+            await validateCanonicalTermOwnership(publication.repository(context.services), context.guildId, draft);
+            if (!(await revalidatePublication(context)))
+                throw new DashboardActionValidationError("Enable Auto Moderation and check your rule publishing permission before saving.");
+            let created;
+            try {
+                created = await publication.repository(context.services).createDraft({
+                    guildId: context.guildId,
+                    draft,
+                    actorUserId: context.actor.userId,
+                    occurredAt: new Date(),
+                });
+                return ruleDetail(await publication.publish({
+                    services: context.services,
+                    current: created,
+                    draft,
+                    actorUserId: context.actor.userId,
+                    revalidate: () => revalidatePublication(context),
+                }));
+            }
+            catch (error) {
+                const failure = validationError(error);
+                throw created
+                    ? new DashboardActionValidationError(`${failure.message} The rule is retained for recovery. Open it in Rules before retrying Save.`)
+                    : failure;
+            }
+        },
+        async update(context, input) {
+            const repository = publication.repository(context.services);
+            const current = await requiredRule(repository, context.guildId, input.resourceId);
+            if (current.revision !== input.expectedRevision)
+                throw new DashboardActionValidationError("This rule changed. Reload and try again.");
+            if (current.status === "drifted" || current.status === "missing")
+                throw new DashboardActionValidationError("Reconcile the owned Discord rule before saving changes.");
+            const draft = validatedDraft(input.value);
+            if (current.nativeRuleId && draft.kind !== current.kind)
+                throw new DashboardActionValidationError("Discord cannot change a mapped rule's filter type. Create a separate rule instead.");
+            await validateRuleReferences(context.services, context.guildId, draft);
+            await validateSingletonKind(repository, context.guildId, draft.kind, current.ruleId);
+            await validateCanonicalTermOwnership(repository, context.guildId, draft, current.ruleId);
+            try {
+                return ruleDetail(await publication.publish({
+                    services: context.services,
+                    current,
+                    draft,
+                    actorUserId: context.actor.userId,
+                    revalidate: () => revalidatePublication(context),
+                }));
+            }
+            catch (error) {
+                throw validationError(error);
+            }
+        },
+        async delete(context, input) {
+            const repository = publication.repository(context.services);
+            const current = await requiredRule(repository, context.guildId, input.resourceId);
+            if (current.revision !== input.expectedRevision)
+                throw new DashboardActionValidationError("This rule changed. Reload and try again.");
+            if (current.status !== "draft" || current.nativeRuleId)
+                throw new DashboardActionValidationError("Only an unmapped draft can be deleted.");
+            const nativeRules = await context.services
+                .get(HELYX_SERVICE_NAMES.discordAutoModeration)
+                .list({ guildId: context.guildId })
+                .catch(() => {
+                throw new DashboardActionValidationError("Discord rule inspection is temporarily unavailable. The rule record was not deleted.");
+            });
+            const ownershipMarker = `${nativeRuleOwnershipMarker(current.ruleId)} `;
+            if (nativeRules.some((rule) => rule.name.startsWith(ownershipMarker)))
+                throw new DashboardActionValidationError("An unconfirmed Discord rule still exists for this record. Review it before deleting the unpublished rule.");
+            const deleted = await repository.deleteDraft({
+                current,
+                actorUserId: context.actor.userId,
+            });
+            if (!deleted.deleted)
+                throw new DashboardActionValidationError("This rule changed. Reload and try again.");
+            return deleted;
+        },
+        async executeAction(context, input) {
+            const repository = publication.repository(context.services);
+            const current = await requiredRule(repository, context.guildId, input.resourceId);
+            if (current.revision !== input.expectedRevision)
+                throw new DashboardActionValidationError("This rule changed. Reload and try again.");
+            try {
+                if (input.actionId === "restore-helyx") {
+                    await validateRuleReferences(context.services, context.guildId, current.draft);
+                    return ruleDetail(await publication.publish({
+                        services: context.services,
+                        current,
+                        draft: current.draft,
+                        actorUserId: context.actor.userId,
+                        revalidate: () => revalidate(context, AUTOMOD_PERMISSION_IDS.rulesReconcile),
+                    }));
+                }
+                if (input.actionId === "disable")
+                    return ruleDetail(await publication.disable({
+                        services: context.services,
+                        current,
+                        actorUserId: context.actor.userId,
+                        revalidate: () => revalidate(context, AUTOMOD_PERMISSION_IDS.rulesPublish),
+                    }));
+                if (input.actionId === "cleanup-owned-discord")
+                    return ruleDetail(await publication.cleanup({
+                        services: context.services,
+                        current,
+                        actorUserId: context.actor.userId,
+                        revalidate: () => revalidate(context, AUTOMOD_PERMISSION_IDS.rulesReconcile),
+                    }));
+                if (input.actionId === "adopt-discord")
+                    return ruleDetail(await adoptDiscord(context.services, current, context.actor.userId, () => revalidate(context, AUTOMOD_PERMISSION_IDS.rulesReconcile)));
+                throw new DashboardActionValidationError("Unknown Auto Moderation rule action.");
+            }
+            catch (error) {
+                throw validationError(error);
+            }
+        },
+    };
+}
+async function adoptDiscord(services, current, actorUserId, revalidateAuthorization) {
+    if (!(await revalidateAuthorization()))
+        throw new Error("Your permission changed before the rule was adopted.");
+    if (!current.nativeRuleId)
+        throw new Error("This rule has no owned Discord mapping to adopt.");
+    const snapshot = await services
+        .get(HELYX_SERVICE_NAMES.discordAutoModeration)
+        .read({ guildId: current.guildId, ruleId: current.nativeRuleId });
+    if (!snapshot)
+        throw new Error("The owned Discord rule is missing.");
+    const configuration = await currentConfiguration(services, current.guildId);
+    const draft = adoptedDraft(current.draft, snapshot, configuration.value.defaultExemptRoleIds, configuration.value.defaultExemptChannelIds);
+    const repository = new AutoModerationRepository(services);
+    await validateCanonicalTermOwnership(repository, current.guildId, draft, current.ruleId);
+    const updated = await repository.updateRule({
+        current,
+        draft,
+        status: snapshot.enabled ? "published" : "disabled",
+        nativeFingerprint: canonicalRuleFingerprint(snapshotDefinition(snapshot)),
+        configurationRevision: configuration.revision,
+        actorUserId,
+        action: "automod.rule-discord-adopted",
+        occurredAt: new Date(),
+    });
+    if (!updated)
+        throw new Error("This rule changed. Reload and try again.");
+    return updated;
+}
+function adoptedDraft(current, snapshot, globalRoles, globalChannels) {
+    const block = snapshot.actions.find((action) => action.type === "block_message");
+    const alert = snapshot.actions.find((action) => action.type === "send_alert_message");
+    const timeoutAction = snapshot.actions.find((action) => action.type === "timeout");
+    const duration = timeoutAction?.type === "timeout" ? timeoutAction.durationSeconds : null;
+    if (duration !== null && !AUTOMOD_TIMEOUT_SECONDS.includes(duration))
+        throw new Error("The Discord rule uses a timeout duration outside Helyx's fixed choices.");
+    const trigger = snapshot.trigger;
+    return {
+        ...current,
+        kind: trigger.type,
+        keywordFilter: trigger.type === "keyword" ? trigger.keywordFilter : [],
+        regexPatterns: trigger.type === "keyword" ? trigger.regexPatterns : [],
+        allowList: trigger.type === "keyword" || trigger.type === "keyword_preset"
+            ? trigger.allowList
+            : [],
+        presets: trigger.type === "keyword_preset" ? trigger.presets : [],
+        mentionTotalLimit: trigger.type === "mention_spam" ? trigger.mentionTotalLimit : 5,
+        mentionRaidProtectionEnabled: trigger.type === "mention_spam" && trigger.mentionRaidProtectionEnabled,
+        blockMessage: Boolean(block),
+        blockExplanation: block?.type === "block_message" ? (block.customMessage ?? null) : null,
+        alertChannelId: alert?.type === "send_alert_message" ? alert.channelId : null,
+        nativeTimeoutSeconds: duration,
+        ignoredRoleIds: snapshot.exemptRoleIds.filter((id) => !globalRoles.includes(id)),
+        ignoredChannelIds: snapshot.exemptChannelIds.filter((id) => !globalChannels.includes(id)),
+    };
+}
+async function revalidate(context, permissionId) {
+    if (!context.services.has(HELYX_SERVICE_NAMES.resourceAuthorization))
+        return false;
+    return context.services
+        .get(HELYX_SERVICE_NAMES.resourceAuthorization)
+        .canUse({
+        guildId: context.guildId,
+        moduleId: AUTOMOD_MODULE_ID,
+        permissionId,
+        actor: context.actor,
+    });
+}
+async function revalidatePublication(context) {
+    if (!context.services.has(HELYX_SERVICE_NAMES.installations))
+        return false;
+    return ((await context.services
+        .get(HELYX_SERVICE_NAMES.installations)
+        .isModuleEnabled(context.guildId, AUTOMOD_MODULE_ID)) &&
+        revalidate(context, AUTOMOD_PERMISSION_IDS.rulesPublish));
+}
+async function requiredRule(repository, guildId, ruleId) {
+    const rule = await repository.findRule(guildId, ruleId);
+    if (!rule)
+        throw new DashboardActionValidationError("Auto Moderation rule was not found.");
+    return rule;
+}
+function snapshotDefinition(snapshot) {
+    return {
+        name: snapshot.name,
+        enabled: snapshot.enabled,
+        eventType: snapshot.eventType,
+        trigger: snapshot.trigger,
+        actions: snapshot.actions,
+        exemptRoleIds: snapshot.exemptRoleIds,
+        exemptChannelIds: snapshot.exemptChannelIds,
+    };
+}
+function validationError(error) {
+    return error instanceof DashboardActionValidationError
+        ? error
+        : new DashboardActionValidationError(error instanceof Error
+            ? error.message
+            : "Auto Moderation rejected the operation.");
+}
+function validatedDraft(value) {
+    try {
+        return parseRuleDraft(value);
+    }
+    catch (error) {
+        throw validationError(error);
+    }
+}
+function validStatus(value) {
+    return Boolean(value &&
+        ["draft", "published", "disabled", "drifted", "missing", "review"].includes(value));
+}
+async function validateCanonicalTermOwnership(repository, guildId, draft, excludedRuleId) {
+    if (draft.kind !== "keyword")
+        return;
+    const incoming = new Set(draft.keywordFilter.map((term) => canonicalTermKey(term.replaceAll("*", ""))));
+    let cursor = null;
+    do {
+        const page = await repository.listRules({
+            guildId,
+            limit: AUTOMOD_LIMITS.rulePageSize,
+            ...(cursor ? { cursor } : {}),
+        });
+        const conflict = page.items.find((rule) => rule.ruleId !== excludedRuleId &&
+            rule.draft.kind === "keyword" &&
+            rule.category !== draft.category &&
+            rule.draft.keywordFilter.some((term) => incoming.has(canonicalTermKey(term.replaceAll("*", "")))));
+        if (conflict)
+            throw new DashboardActionValidationError(`A canonical term is already owned by ${conflict.name} in the ${conflict.category} category. Choose one category owner.`);
+        cursor = page.nextCursor;
+    } while (cursor);
+}
+//# sourceMappingURL=resources.js.map

package/dist/scanner-configuration.d.ts

@@ -0,0 +1,10 @@
+import { type AutoModerationScannerConfigurationPageV1, type ServiceAccess } from "@helyx/sdk";
+export declare function createScannerConfigurationSource(): {
+    getPage(services: ServiceAccess, input: {
+        cursor?: string;
+        limit: number;
+        knownFingerprint?: string;
+    }): Promise<AutoModerationScannerConfigurationPageV1>;
+    invalidate(): void;
+};
+//# sourceMappingURL=scanner-configuration.d.ts.map