@helyx/module-automod 1.0.1

package/dist/publication-support.js

@@ -0,0 +1,69 @@
+import { HELYX_SERVICE_NAMES, } from "@helyx/sdk";
+import { DEFAULT_AUTOMOD_CONFIGURATION, parseAutoModerationConfiguration, } from "./configuration.js";
+import { AUTOMOD_MODULE_ID } from "./constants.js";
+import { toNativeDefinition } from "./domain.js";
+export function isKindEnabled(draft, configuration) {
+    if (draft.kind === "keyword_preset")
+        return configuration.presetRuleEnabled;
+    if (draft.kind === "spam")
+        return configuration.genericSpamRuleEnabled;
+    if (draft.kind === "mention_spam")
+        return configuration.mentionSpamRuleEnabled;
+    return true;
+}
+export function validateKindEnabled(draft, configuration) {
+    if (isKindEnabled(draft, configuration))
+        return;
+    throw new Error(`Enable the ${draft.kind.replaceAll("_", " ")} rule setting before publishing this rule.`);
+}
+export async function currentConfiguration(services, guildId) {
+    if (!services.has(HELYX_SERVICE_NAMES.configuration))
+        return { value: DEFAULT_AUTOMOD_CONFIGURATION, revision: "0" };
+    const stored = await services
+        .get(HELYX_SERVICE_NAMES.configuration)
+        .get(guildId, AUTOMOD_MODULE_ID);
+    return stored
+        ? {
+            value: parseAutoModerationConfiguration(stored.value),
+            revision: stored.version.toString(),
+        }
+        : { value: DEFAULT_AUTOMOD_CONFIGURATION, revision: "0" };
+}
+export function definitionFor(ruleId, draft, configuration, enabled) {
+    return toNativeDefinition({
+        ruleId,
+        draft,
+        enabled,
+        globalIgnoredRoleIds: configuration.defaultExemptRoleIds,
+        globalIgnoredChannelIds: configuration.defaultExemptChannelIds,
+        defaultAlertChannelId: configuration.defaultNativeAlertChannelId,
+    });
+}
+export 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,
+    };
+}
+export function publicationError(outcome, safeCode) {
+    const explanations = {
+        capacity_exceeded: "Discord has no remaining capacity for this Auto Moderation rule type.",
+        missing_permission: "Helyx is missing a Discord permission required to publish this rule.",
+        invalid_rule: "Discord rejected this Auto Moderation rule definition.",
+        ambiguous: "Discord did not confirm whether the rule changed. Review the mapping before retrying.",
+        already_absent: "The owned Discord rule is missing.",
+    };
+    return new Error(explanations[outcome] ??
+        `The Discord Auto Moderation operation failed${safeCode ? ` (${safeCode})` : ""}.`);
+}
+export function mutationSafeCode(result) {
+    return "safeCode" in result && typeof result.safeCode === "string"
+        ? result.safeCode
+        : undefined;
+}
+//# sourceMappingURL=publication-support.js.map

package/dist/publication.d.ts

@@ -0,0 +1,32 @@
+import { type DiscordAutoModerationRuleSnapshot, type ServiceAccess } from "@helyx/sdk";
+import { type AutoModerationRuleDraft } from "./domain.js";
+import { AutoModerationRepository, type StoredAutoModerationRule } from "./repository.js";
+export declare class AutoModerationPublicationService {
+    #private;
+    private readonly onEnhancedConfigurationChanged;
+    constructor(onEnhancedConfigurationChanged?: (services: ServiceAccess) => void | Promise<void>);
+    repository(services: ServiceAccess): AutoModerationRepository;
+    publish(input: {
+        services: ServiceAccess;
+        current: StoredAutoModerationRule;
+        draft: AutoModerationRuleDraft;
+        actorUserId: string;
+        revalidate(): Promise<boolean>;
+    }): Promise<StoredAutoModerationRule>;
+    disable(input: {
+        services: ServiceAccess;
+        current: StoredAutoModerationRule;
+        actorUserId: string;
+        revalidate(): Promise<boolean>;
+    }): Promise<StoredAutoModerationRule>;
+    cleanup(input: {
+        services: ServiceAccess;
+        current: StoredAutoModerationRule;
+        actorUserId: string;
+        revalidate(): Promise<boolean>;
+    }): Promise<StoredAutoModerationRule>;
+    observeNativeRule(services: ServiceAccess, snapshot: DiscordAutoModerationRuleSnapshot | null, guildId: string, nativeRuleId: string): Promise<void>;
+    synchronizeOwnedRules(services: ServiceAccess, guildId: string, moduleEnabled: boolean): Promise<void>;
+}
+export { currentConfiguration, definitionFor } from "./publication-support.js";
+//# sourceMappingURL=publication.d.ts.map

package/dist/publication.js

@@ -0,0 +1,333 @@
+import { HELYX_SERVICE_NAMES, } from "@helyx/sdk";
+import { AUTOMOD_MODULE_ID } from "./constants.js";
+import { canonicalRuleFingerprint, nativeRuleOwnershipMarker, } from "./domain.js";
+import { currentConfiguration, definitionFor, isKindEnabled, mutationSafeCode, publicationError, snapshotDefinition, validateKindEnabled, } from "./publication-support.js";
+import { AutoModerationRepository, } from "./repository.js";
+export class AutoModerationPublicationService {
+    onEnhancedConfigurationChanged;
+    #mutatingNativeRules = new Set();
+    constructor(onEnhancedConfigurationChanged = () => { }) {
+        this.onEnhancedConfigurationChanged = onEnhancedConfigurationChanged;
+    }
+    repository(services) {
+        return new AutoModerationRepository(services);
+    }
+    async publish(input) {
+        const configuration = await currentConfiguration(input.services, input.current.guildId);
+        validateKindEnabled(input.draft, configuration.value);
+        if (!(await this.#revalidatePublication(input, configuration.revision)))
+            throw new Error("The rule, settings or your permission changed. Reload and try again.");
+        const definition = definitionFor(input.current.ruleId, input.draft, configuration.value, true);
+        const native = input.services.get(HELYX_SERVICE_NAMES.discordAutoModeration);
+        return input.current.nativeRuleId
+            ? this.#updateNative(input, native, definition, configuration.revision)
+            : this.#createNative(input, native, definition, configuration.revision);
+    }
+    async #createNative(input, native, definition, configurationRevision) {
+        const ownershipMarker = `${nativeRuleOwnershipMarker(input.current.ruleId)} `;
+        const existing = await native
+            .list({ guildId: input.current.guildId })
+            .catch(() => {
+            throw new Error("Discord rule inspection is temporarily unavailable. Try again.");
+        });
+        if (existing.some((rule) => rule.name.startsWith(ownershipMarker) &&
+            canonicalRuleFingerprint(snapshotDefinition(rule)) !==
+                canonicalRuleFingerprint(definition)))
+            throw new Error("An unconfirmed Discord rule already exists for this rule. Review its Discord settings before retrying Save.");
+        const result = await native.create({
+            guildId: input.current.guildId,
+            callerModuleId: AUTOMOD_MODULE_ID,
+            operationKey: input.current.operationKey,
+            rule: definition,
+            revalidate: () => this.#revalidatePublication(input, configurationRevision),
+        });
+        if ((result.outcome !== "succeeded" &&
+            result.outcome !== "already_applied") ||
+            !result.rule)
+            throw publicationError(result.outcome, mutationSafeCode(result));
+        const stored = await this.repository(input.services)
+            .updateRule({
+            current: input.current,
+            draft: input.draft,
+            status: "published",
+            nativeRuleId: result.rule.ruleId,
+            nativeFingerprint: canonicalRuleFingerprint(definition),
+            configurationRevision,
+            actorUserId: input.actorUserId,
+            action: "automod.rule-published",
+            occurredAt: new Date(),
+        })
+            .catch(() => null);
+        if (!stored) {
+            if (result.outcome === "succeeded")
+                await native.delete({
+                    guildId: input.current.guildId,
+                    ruleId: result.rule.ruleId,
+                    callerModuleId: AUTOMOD_MODULE_ID,
+                    operationKey: `${input.current.operationKey}:compensate`,
+                    revalidate: async () => {
+                        const latest = await this.repository(input.services).findRule(input.current.guildId, input.current.ruleId);
+                        return Boolean(latest && latest.nativeRuleId !== result.rule.ruleId);
+                    },
+                });
+            throw new Error("The rule changed while it was being published. Discord was compensated where safe.");
+        }
+        await this.onEnhancedConfigurationChanged(input.services);
+        return stored;
+    }
+    async #updateNative(input, native, definition, configurationRevision) {
+        const nativeRuleId = input.current.nativeRuleId;
+        const mutationKey = `${input.current.guildId}:${nativeRuleId}`;
+        this.#mutatingNativeRules.add(mutationKey);
+        try {
+            const previous = await native.read({
+                guildId: input.current.guildId,
+                ruleId: nativeRuleId,
+            });
+            if (!previous) {
+                await this.#mark(input.services, input.current, "missing", "automod.rule-missing");
+                throw new Error("The owned Discord rule is missing. Review it before creating a replacement.");
+            }
+            const result = await native.update({
+                guildId: input.current.guildId,
+                ruleId: nativeRuleId,
+                callerModuleId: AUTOMOD_MODULE_ID,
+                operationKey: input.current.operationKey,
+                rule: definition,
+                revalidate: () => this.#revalidatePublication(input, configurationRevision),
+            });
+            if (result.outcome !== "succeeded" &&
+                result.outcome !== "already_applied")
+                throw publicationError(result.outcome, mutationSafeCode(result));
+            const stored = await this.repository(input.services)
+                .updateRule({
+                current: input.current,
+                draft: input.draft,
+                status: "published",
+                nativeRuleId,
+                nativeFingerprint: canonicalRuleFingerprint(definition),
+                configurationRevision,
+                actorUserId: input.actorUserId,
+                action: "automod.rule-published",
+                occurredAt: new Date(),
+            })
+                .catch(() => null);
+            if (!stored) {
+                if (result.outcome === "succeeded")
+                    await native.update({
+                        guildId: input.current.guildId,
+                        ruleId: nativeRuleId,
+                        callerModuleId: AUTOMOD_MODULE_ID,
+                        operationKey: `${input.current.operationKey}:compensate`,
+                        rule: snapshotDefinition(previous),
+                        revalidate: async () => {
+                            const latest = await this.repository(input.services).findRule(input.current.guildId, input.current.ruleId);
+                            const actual = await native.read({
+                                guildId: input.current.guildId,
+                                ruleId: nativeRuleId,
+                            });
+                            return Boolean(latest &&
+                                latest.nativeRuleId === nativeRuleId &&
+                                latest.nativeFingerprint === input.current.nativeFingerprint &&
+                                actual &&
+                                canonicalRuleFingerprint(snapshotDefinition(actual)) ===
+                                    canonicalRuleFingerprint(definition));
+                        },
+                    });
+                throw new Error("The rule changed while it was being published. Discord was restored where safe.");
+            }
+            await this.onEnhancedConfigurationChanged(input.services);
+            return stored;
+        }
+        finally {
+            this.#mutatingNativeRules.delete(mutationKey);
+        }
+    }
+    async #revalidatePublication(input, configurationRevision) {
+        const current = await this.repository(input.services).findRule(input.current.guildId, input.current.ruleId);
+        const configuration = await currentConfiguration(input.services, input.current.guildId);
+        return Boolean(current &&
+            current.revision === input.current.revision &&
+            configuration.revision === configurationRevision &&
+            (await input.revalidate()));
+    }
+    async disable(input) {
+        if (!input.current.nativeRuleId)
+            throw new Error("This rule has no owned Discord mapping.");
+        const configuration = await currentConfiguration(input.services, input.current.guildId);
+        const definition = definitionFor(input.current.ruleId, input.current.draft, configuration.value, false);
+        const mutationKey = `${input.current.guildId}:${input.current.nativeRuleId}`;
+        this.#mutatingNativeRules.add(mutationKey);
+        try {
+            const result = await input.services
+                .get(HELYX_SERVICE_NAMES.discordAutoModeration)
+                .update({
+                guildId: input.current.guildId,
+                ruleId: input.current.nativeRuleId,
+                callerModuleId: AUTOMOD_MODULE_ID,
+                operationKey: `${input.current.operationKey}:disable`,
+                rule: definition,
+                revalidate: () => input.revalidate(),
+            });
+            if (result.outcome !== "succeeded" &&
+                result.outcome !== "already_applied")
+                throw publicationError(result.outcome, mutationSafeCode(result));
+            const updated = await this.repository(input.services).updateRule({
+                current: input.current,
+                status: "disabled",
+                nativeFingerprint: canonicalRuleFingerprint(definition),
+                configurationRevision: configuration.revision,
+                actorUserId: input.actorUserId,
+                action: "automod.rule-disabled",
+                occurredAt: new Date(),
+            });
+            if (!updated)
+                throw new Error("The rule changed while it was being disabled.");
+            await this.onEnhancedConfigurationChanged(input.services);
+            return updated;
+        }
+        finally {
+            this.#mutatingNativeRules.delete(mutationKey);
+        }
+    }
+    async cleanup(input) {
+        if (!input.current.nativeRuleId)
+            return input.current;
+        const mutationKey = `${input.current.guildId}:${input.current.nativeRuleId}`;
+        this.#mutatingNativeRules.add(mutationKey);
+        try {
+            const result = await input.services
+                .get(HELYX_SERVICE_NAMES.discordAutoModeration)
+                .delete({
+                guildId: input.current.guildId,
+                ruleId: input.current.nativeRuleId,
+                callerModuleId: AUTOMOD_MODULE_ID,
+                operationKey: `${input.current.operationKey}:cleanup`,
+                revalidate: () => input.revalidate(),
+            });
+            if (result.outcome !== "succeeded" && result.outcome !== "already_absent")
+                throw publicationError(result.outcome, mutationSafeCode(result));
+            const updated = await this.repository(input.services).updateRule({
+                current: input.current,
+                status: "draft",
+                nativeRuleId: null,
+                nativeFingerprint: null,
+                actorUserId: input.actorUserId,
+                action: "automod.rule-native-cleaned",
+                occurredAt: new Date(),
+            });
+            if (!updated)
+                throw new Error("The rule changed while cleanup completed.");
+            await this.onEnhancedConfigurationChanged(input.services);
+            return updated;
+        }
+        finally {
+            this.#mutatingNativeRules.delete(mutationKey);
+        }
+    }
+    async observeNativeRule(services, snapshot, guildId, nativeRuleId) {
+        if (this.#mutatingNativeRules.has(`${guildId}:${nativeRuleId}`))
+            return;
+        const current = await this.repository(services).findByNativeRuleId(guildId, nativeRuleId);
+        if (!current)
+            return;
+        if (!snapshot) {
+            await this.#mark(services, current, "missing", "automod.rule-missing");
+            return;
+        }
+        const configuration = await currentConfiguration(services, guildId);
+        const expected = definitionFor(current.ruleId, current.draft, configuration.value, current.status !== "disabled" &&
+            isKindEnabled(current.draft, configuration.value));
+        if (canonicalRuleFingerprint(snapshotDefinition(snapshot)) !==
+            canonicalRuleFingerprint(expected))
+            await this.#mark(services, current, "drifted", "automod.rule-drifted");
+    }
+    async synchronizeOwnedRules(services, guildId, moduleEnabled) {
+        let cursor;
+        do {
+            const page = await this.repository(services).listRules({
+                guildId,
+                limit: 50,
+                ...(cursor ? { cursor } : {}),
+            });
+            for (const current of page.items) {
+                if (!current.nativeRuleId ||
+                    current.status === "missing" ||
+                    current.status === "review")
+                    continue;
+                const mutationKey = `${guildId}:${current.nativeRuleId}`;
+                this.#mutatingNativeRules.add(mutationKey);
+                try {
+                    const configuration = await currentConfiguration(services, guildId);
+                    const enabled = moduleEnabled &&
+                        current.status === "published" &&
+                        isKindEnabled(current.draft, configuration.value);
+                    const definition = definitionFor(current.ruleId, current.draft, configuration.value, enabled);
+                    const result = await services
+                        .get(HELYX_SERVICE_NAMES.discordAutoModeration)
+                        .update({
+                        guildId,
+                        ruleId: current.nativeRuleId,
+                        callerModuleId: AUTOMOD_MODULE_ID,
+                        operationKey: `${current.operationKey}:${moduleEnabled ? "synchronise" : "deactivate"}`,
+                        rule: definition,
+                        revalidate: () => Promise.resolve(true),
+                    });
+                    if (result.outcome === "succeeded" ||
+                        result.outcome === "already_applied")
+                        await this.repository(services).updateRule({
+                            current,
+                            status: current.status,
+                            nativeFingerprint: canonicalRuleFingerprint(definition),
+                            configurationRevision: configuration.revision,
+                            actorUserId: null,
+                            action: moduleEnabled
+                                ? "automod.rule-synchronised"
+                                : "automod.rule-deactivated",
+                            occurredAt: new Date(),
+                        });
+                    else
+                        await this.#mark(services, current, "review", "automod.rule-sync-failed");
+                }
+                catch {
+                    await this.#mark(services, current, "review", "automod.rule-sync-failed").catch(() => undefined);
+                }
+                finally {
+                    this.#mutatingNativeRules.delete(mutationKey);
+                }
+            }
+            cursor = page.nextCursor ?? undefined;
+        } while (cursor);
+        await this.onEnhancedConfigurationChanged(services);
+    }
+    async #mark(services, current, status, action) {
+        const updated = await this.repository(services).updateRule({
+            current,
+            status,
+            actorUserId: null,
+            action,
+            occurredAt: new Date(),
+        });
+        if (updated &&
+            status === "drifted" &&
+            services.has(HELYX_SERVICE_NAMES.moduleLogging))
+            await services
+                .get(HELYX_SERVICE_NAMES.moduleLogging)
+                .emit({
+                guildId: current.guildId,
+                moduleId: AUTOMOD_MODULE_ID,
+                eventId: "automod-rule-drifted",
+                summary: "A Helyx-owned Discord Auto Moderation rule drifted.",
+                details: [
+                    { label: "Rule", value: current.ruleId },
+                    { label: "Outcome", value: "Manager review required" },
+                ],
+                idempotencyKey: `${current.ruleId}:${current.revision}:drift`,
+            })
+                .catch(() => undefined);
+        if (updated)
+            await this.onEnhancedConfigurationChanged(services);
+    }
+}
+export { currentConfiguration, definitionFor } from "./publication-support.js";
+//# sourceMappingURL=publication.js.map

package/dist/receipt-statistics.d.ts

@@ -0,0 +1,11 @@
+import { type ServiceAccess } from "@helyx/sdk";
+/** Counts an observed receipt once through the transactional record contract. */
+export declare function countAutoModerationReceipt(services: ServiceAccess, input: {
+    guildId: string;
+    ruleId: string;
+    eventKey: string;
+    source: "native" | "enhanced";
+    actionType: string;
+    occurredAt: Date;
+}): Promise<void>;
+//# sourceMappingURL=receipt-statistics.d.ts.map

package/dist/receipt-statistics.js

@@ -0,0 +1,58 @@
+import { HELYX_SERVICE_NAMES, } from "@helyx/sdk";
+import { createHash } from "node:crypto";
+import { AUTOMOD_LIMITS, AUTOMOD_MODULE_ID } from "./constants.js";
+/** Counts an observed receipt once through the transactional record contract. */
+export async function countAutoModerationReceipt(services, input) {
+    if (!services.has(HELYX_SERVICE_NAMES.records))
+        return;
+    const day = input.occurredAt.toISOString().slice(0, 10);
+    const retentionAt = new Date(`${day}T00:00:00.000Z`);
+    retentionAt.setUTCDate(retentionAt.getUTCDate() + AUTOMOD_LIMITS.settledClaimRetentionDays + 1);
+    const identity = {
+        guild_id: input.guildId,
+        rule_id: input.ruleId,
+        day,
+        source: input.source,
+        action_type: input.actionType,
+    };
+    // The numeric record API requires a UUID, not the receipt's string key.
+    // A namespaced UUIDv8 keeps retries deterministic without exposing content.
+    const bytes = createHash("sha256")
+        .update(JSON.stringify([AUTOMOD_MODULE_ID, "daily-count", input.eventKey]))
+        .digest()
+        .subarray(0, 16);
+    bytes[6] = (bytes[6] & 0x0f) | 0x80;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = bytes.toString("hex");
+    const operationId = `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+    await services
+        .get(HELYX_SERVICE_NAMES.records)
+        .mutateNumericBatch({
+        moduleId: AUTOMOD_MODULE_ID,
+        collection: "daily_counts",
+        operationId,
+        uniqueBy: ["guild_id", "rule_id", "day", "source", "action_type"],
+        mutations: [
+            {
+                identity,
+                insert: {
+                    ...identity,
+                    observed_count: 0,
+                    last_observed_at: input.occurredAt,
+                },
+                increments: { observed_count: 1 },
+                maxima: { last_observed_at: input.occurredAt },
+            },
+        ],
+        select: ["observed_count", "last_observed_at"],
+        retention: [
+            {
+                collection: "daily_counts",
+                where: { guild_id: input.guildId, day },
+                scheduledFor: retentionAt,
+                idempotencyKey: `daily-counts:${input.guildId}:${day}`,
+            },
+        ],
+    });
+}
+//# sourceMappingURL=receipt-statistics.js.map