@helyx/module-moderation 1.0.1

package/dist/provider.js

@@ -0,0 +1,335 @@
+import { HELYX_SERVICE_NAMES, MODERATION_ACTION_CONTRACT_VERSION, MODERATION_ACTION_PROVIDER_ID, } from "@helyx/sdk";
+import { DEFAULT_MODERATION_CONFIGURATION, parseModerationConfiguration, } from "./configuration.js";
+import { MODERATION_MODULE_ID } from "./constants.js";
+import { appendModerationAudit, emitAutomaticModerationActionLog, moderationRetentionExpiresAt, sendWarningDirectMessage, } from "./action-support.js";
+const ALLOWED_CALLERS = Object.freeze(["helyx.automod"]);
+export function createModerationActionProvider(runtime) {
+    return {
+        providerId: MODERATION_ACTION_PROVIDER_ID,
+        contractVersion: MODERATION_ACTION_CONTRACT_VERSION,
+        allowedCallerModuleIds: ALLOWED_CALLERS,
+        execute: (context, request) => execute(runtime, context, request),
+    };
+}
+async function execute(runtime, context, request) {
+    const services = context.services;
+    if (!ALLOWED_CALLERS.includes(request.callerModuleId))
+        return { outcome: "rejected", code: "caller_not_allowed" };
+    if (!(await automaticRequestStillAllowed(services, request)))
+        return { outcome: "rejected", code: "subject_exempt" };
+    const configuration = await moderationConfiguration(services, request.guildId).catch(() => null);
+    if (!configuration)
+        return { outcome: "rejected", code: "module_unavailable" };
+    const pending = await atomicCases(services).createConfirmedAutoModerationOffenceCase({
+        operationKey: request.operationKey,
+        guildId: request.guildId,
+        subjectUserId: request.subjectUserId,
+        sourceModuleId: request.callerModuleId,
+        sourceEventId: request.sourceEventId,
+        sourceMessage: request.sourceMessage,
+        ruleId: request.ruleId,
+        ruleRevision: request.policy.ruleRevision,
+        configurationRevision: request.configurationRevision,
+        policyFingerprint: request.policy.policyFingerprint,
+        actionPolicy: request.policy.actionPolicy,
+        repeatWindowStartsAt: request.policy.windowStartsAt,
+        reasonCode: request.reasonCode,
+        ...(request.evidenceReference
+            ? { evidenceReference: request.evidenceReference }
+            : {}),
+        openViolationThread: request.policy.openViolationThread,
+        occurredAt: request.occurredAt,
+        ...(request.requestKind === "observation"
+            ? { observedAction: request.observedAction }
+            : {}),
+    });
+    if (pending.outcome === "rejected")
+        return rejectedCreate(pending.code);
+    if (pending.outcome === "replayed") {
+        if (pending.attemptOutcome === "pending" ||
+            pending.attemptOutcome === "ambiguous")
+            await scheduleReconciliation(services, request, pending.caseId, pending.attemptId);
+        const replayThread = request.policy.openViolationThread && applied(pending.attemptOutcome)
+            ? await runtime
+                .deliverViolationThread({
+                services,
+                guildId: request.guildId,
+                caseId: pending.caseId,
+                caseNumber: pending.caseNumber,
+                caseRevision: pending.revision,
+                subjectUserId: request.subjectUserId,
+                severity: request.severity,
+                operationKey: request.operationKey,
+                evidence: context.violationEvidence,
+            })
+                .catch(() => "review_required")
+            : "not_requested";
+        if (!applied(pending.attemptOutcome))
+            return {
+                outcome: pending.attemptOutcome === "pending" ||
+                    pending.attemptOutcome === "ambiguous"
+                    ? "ambiguous"
+                    : pending.attemptOutcome === "review_required"
+                        ? "review_required"
+                        : "failed",
+                caseId: pending.caseId,
+                caseNumber: pending.caseNumber,
+                safeCode: `replayed_${pending.attemptOutcome}`,
+                replayed: true,
+            };
+        return {
+            outcome: "already_applied",
+            caseId: pending.caseId,
+            caseNumber: pending.caseNumber,
+            offenceOrdinal: pending.offenceOrdinal,
+            selectedAction: pending.selectedAction,
+            actionOutcome: "already_applied",
+            threadOutcome: replayThread,
+            ...(replayThread === "retry_pending" || replayThread === "review_required"
+                ? { safeCode: `thread_${replayThread}` }
+                : {}),
+            replayed: true,
+        };
+    }
+    try {
+        await appendModerationAudit(services, {
+            guildId: request.guildId,
+            action: "moderation.action-attempt",
+            source: "system",
+            idempotencyKey: `${request.operationKey}:audit`,
+            targetType: "moderation_case",
+            targetId: pending.caseId,
+            metadata: {
+                action: pending.selectedAction.type,
+                caseNumber: pending.caseNumber,
+                deleteSourceMessage: request.policy.deleteSourceMessage === true,
+            },
+        });
+    }
+    catch {
+        const settledAt = new Date();
+        await atomicCases(services).settleActionAttempt({
+            operationKey: `${request.operationKey}:audit-failed`,
+            guildId: request.guildId,
+            caseId: pending.caseId,
+            attemptId: pending.attemptId,
+            expectedRevision: pending.revision,
+            outcome: "failed",
+            safeCode: "audit_unavailable",
+            retentionExpiresAt: moderationRetentionExpiresAt(settledAt, configuration.caseRetentionDays),
+            occurredAt: settledAt,
+        });
+        return {
+            outcome: "failed",
+            caseId: pending.caseId,
+            caseNumber: pending.caseNumber,
+            safeCode: "audit_unavailable",
+            replayed: false,
+        };
+    }
+    const messageRemoval = request.detectionSource === "enhanced" &&
+        request.policy.deleteSourceMessage === true &&
+        pending.selectedAction.type !== "delete_message"
+        ? await runtime
+            .dispatchAction(services, {
+            guildId: request.guildId,
+            subjectUserId: request.subjectUserId,
+            action: { type: "delete_message" },
+            reason: boundedAuditReason(pending.caseNumber, "Automatic message removal"),
+            operationKey: `${request.operationKey}:block-message`,
+            sourceMessage: request.sourceMessage,
+            protectedRoleIds: [],
+            revalidate: () => automaticRequestStillAllowed(services, request),
+        })
+            .catch(() => ({ outcome: "ambiguous" }))
+        : null;
+    const effect = await runtime
+        .dispatchAction(services, {
+        guildId: request.guildId,
+        subjectUserId: request.subjectUserId,
+        action: pending.selectedAction,
+        reason: boundedAuditReason(pending.caseNumber, `Automatic moderation: ${request.reasonCode}`),
+        operationKey: `${request.operationKey}:discord`,
+        sourceMessage: request.sourceMessage,
+        protectedRoleIds: [
+            ...request.policy.globalIgnoredRoleIds,
+            ...request.policy.ruleIgnoredRoleIds,
+            ...(configuration.violationAccessRoleId
+                ? [configuration.violationAccessRoleId]
+                : []),
+        ],
+        revalidate: () => automaticRequestStillAllowed(services, request),
+    })
+        .catch(() => ({
+        outcome: "ambiguous",
+        safeCode: "enforcement_unavailable",
+    }));
+    const settledAt = new Date();
+    const settlement = await atomicCases(services)
+        .settleActionAttempt({
+        operationKey: `${request.operationKey}:settle`,
+        guildId: request.guildId,
+        caseId: pending.caseId,
+        attemptId: pending.attemptId,
+        expectedRevision: pending.revision,
+        outcome: effect.outcome,
+        ...(effect.safeCode ? { safeCode: effect.safeCode } : {}),
+        ...("removedRoleIds" in effect && effect.removedRoleIds
+            ? { removedRoleIds: effect.removedRoleIds }
+            : {}),
+        retentionExpiresAt: moderationRetentionExpiresAt(settledAt, configuration.caseRetentionDays),
+        occurredAt: settledAt,
+    })
+        .catch(() => null);
+    if (!settlement) {
+        await scheduleReconciliation(services, request, pending.caseId, pending.attemptId).catch(() => undefined);
+        return {
+            outcome: "review_required",
+            caseId: pending.caseId,
+            caseNumber: pending.caseNumber,
+            safeCode: "settlement_unavailable",
+            replayed: false,
+        };
+    }
+    if (settlement.outcome === "rejected")
+        return {
+            outcome: "review_required",
+            caseId: pending.caseId,
+            caseNumber: pending.caseNumber,
+            safeCode: `settlement_${settlement.code}`,
+            replayed: false,
+        };
+    if (effect.outcome === "ambiguous")
+        await scheduleReconciliation(services, request, pending.caseId, pending.attemptId);
+    if (applied(effect.outcome))
+        await emitAutomaticModerationActionLog(services, {
+            guildId: request.guildId,
+            action: pending.selectedAction,
+            caseId: pending.caseId,
+            caseNumber: pending.caseNumber,
+            subjectUserId: request.subjectUserId,
+            operationKey: request.operationKey,
+        });
+    if (applied(effect.outcome) && pending.selectedAction.type === "warn")
+        await sendWarningDirectMessage(services, {
+            guildId: request.guildId,
+            caseId: pending.caseId,
+            caseNumber: pending.caseNumber,
+            subjectUserId: request.subjectUserId,
+        }).catch(() => undefined);
+    const threadOutcome = request.policy.openViolationThread && applied(effect.outcome)
+        ? await runtime
+            .deliverViolationThread({
+            services,
+            guildId: request.guildId,
+            caseId: pending.caseId,
+            caseNumber: pending.caseNumber,
+            caseRevision: settlement.revision,
+            subjectUserId: request.subjectUserId,
+            severity: request.severity,
+            operationKey: request.operationKey,
+            evidence: context.violationEvidence,
+        })
+            .catch(() => "review_required")
+        : "not_requested";
+    if (!applied(effect.outcome))
+        return {
+            outcome: effect.outcome === "ambiguous"
+                ? "ambiguous"
+                : effect.outcome === "review_required"
+                    ? "review_required"
+                    : "failed",
+            caseId: pending.caseId,
+            caseNumber: pending.caseNumber,
+            ...(effect.safeCode ? { safeCode: effect.safeCode } : {}),
+            replayed: false,
+        };
+    return {
+        outcome: "applied",
+        caseId: pending.caseId,
+        caseNumber: pending.caseNumber,
+        offenceOrdinal: pending.offenceOrdinal,
+        selectedAction: pending.selectedAction,
+        actionOutcome: effect.outcome === "succeeded" ? "succeeded" : "already_applied",
+        threadOutcome,
+        ...(!messageRemoval || applied(messageRemoval.outcome)
+            ? threadOutcome === "retry_pending" || threadOutcome === "review_required"
+                ? { safeCode: `thread_${threadOutcome}` }
+                : {}
+            : { safeCode: "message_removal_unconfirmed" }),
+        replayed: false,
+    };
+}
+async function automaticRequestStillAllowed(services, request) {
+    if (!services.has(HELYX_SERVICE_NAMES.installations) ||
+        !(await services
+            .get(HELYX_SERVICE_NAMES.installations)
+            .isModuleEnabled(request.guildId, MODERATION_MODULE_ID)) ||
+        (services.has(HELYX_SERVICE_NAMES.moduleAvailability) &&
+            !(await services
+                .get(HELYX_SERVICE_NAMES.moduleAvailability)
+                .isAvailable(MODERATION_MODULE_ID))) ||
+        !(await request.revalidatePolicy()))
+        return false;
+    const member = await services
+        .get(HELYX_SERVICE_NAMES.memberEnforcement)
+        .inspectMember({
+        guildId: request.guildId,
+        memberUserId: request.subjectUserId,
+    });
+    if (member.outcome !== "present" ||
+        member.isGuildOwner ||
+        member.isAdministrator ||
+        member.isBot ||
+        member.helyxHierarchy !== "above")
+        return false;
+    const ignored = new Set([
+        ...request.policy.globalIgnoredRoleIds,
+        ...request.policy.ruleIgnoredRoleIds,
+    ]);
+    return !member.roleIds.some((roleId) => ignored.has(roleId));
+}
+function rejectedCreate(code) {
+    return {
+        outcome: "rejected",
+        code: code === "operation_key_conflict"
+            ? "operation_key_conflict"
+            : code === "stale_policy"
+                ? "stale_operation"
+                : "invalid_request",
+    };
+}
+function atomicCases(services) {
+    return services.get(HELYX_SERVICE_NAMES.atomicModerationCases);
+}
+async function moderationConfiguration(services, guildId) {
+    if (!services.has(HELYX_SERVICE_NAMES.configuration))
+        return DEFAULT_MODERATION_CONFIGURATION;
+    const stored = await services
+        .get(HELYX_SERVICE_NAMES.configuration)
+        .get(guildId, MODERATION_MODULE_ID);
+    return stored
+        ? parseModerationConfiguration(stored.value)
+        : DEFAULT_MODERATION_CONFIGURATION;
+}
+async function scheduleReconciliation(services, request, caseId, attemptId) {
+    if (!services.has(HELYX_SERVICE_NAMES.scheduledTasks))
+        return;
+    await services
+        .get(HELYX_SERVICE_NAMES.scheduledTasks)
+        .schedule({
+        moduleId: MODERATION_MODULE_ID,
+        taskKind: "moderation.action-reconcile",
+        guildId: request.guildId,
+        idempotencyKey: `${request.operationKey}:reconcile`,
+        payload: { caseId, attemptId },
+        scheduledFor: new Date(Date.now() + 2_000),
+    });
+}
+function applied(outcome) {
+    return outcome === "succeeded" || outcome === "already_applied";
+}
+function boundedAuditReason(caseNumber, reason) {
+    return `[Helyx case ${caseNumber}] ${reason}`.slice(0, 512);
+}
+//# sourceMappingURL=provider.js.map

package/dist/receipt-repository.d.ts

@@ -0,0 +1,9 @@
+import type { ModuleRecordService } from "@helyx/sdk";
+import { type StoredModerationDmReceipt } from "./repository-model.js";
+export declare class ModerationReceiptRepository {
+    private readonly records;
+    constructor(records: ModuleRecordService);
+    findDmReceipt(guildId: string, caseId: string): Promise<StoredModerationDmReceipt | null>;
+    upsertDmReceipt(input: StoredModerationDmReceipt): Promise<void>;
+}
+//# sourceMappingURL=receipt-repository.d.ts.map

package/dist/receipt-repository.js

@@ -0,0 +1,36 @@
+import { MODERATION_MODULE_ID } from "./constants.js";
+import { DM_RECEIPT_FIELDS, dmReceiptWrite, mapDmReceipt, } from "./repository-model.js";
+export class ModerationReceiptRepository {
+    records;
+    constructor(records) {
+        this.records = records;
+    }
+    async findDmReceipt(guildId, caseId) {
+        const row = await this.records.findOne({
+            moduleId: MODERATION_MODULE_ID,
+            collection: "dm_receipts",
+            select: DM_RECEIPT_FIELDS,
+            where: { guild_id: guildId, case_id: caseId },
+        });
+        return row ? mapDmReceipt(row) : null;
+    }
+    async upsertDmReceipt(input) {
+        const write = dmReceiptWrite(input);
+        await this.records.upsert({
+            moduleId: MODERATION_MODULE_ID,
+            collection: "dm_receipts",
+            values: write.values,
+            uniqueBy: ["guild_id", "case_id"],
+            update: [
+                "template_revision",
+                "delivery_state",
+                "safe_code",
+                "message_id",
+                "attempted_at",
+                "updated_at",
+            ].filter((field) => Object.hasOwn(write.values, field)),
+            clear: write.clear,
+        });
+    }
+}
+//# sourceMappingURL=receipt-repository.js.map