@helyx/module-moderation 1.0.1

package/dist/contracts.d.ts

@@ -0,0 +1,109 @@
+import { MODERATION_COMMAND_IDS } from "./constants.js";
+export type ModerationCommandId = (typeof MODERATION_COMMAND_IDS)[keyof typeof MODERATION_COMMAND_IDS];
+export type ModerationCaseAction = "warn" | "timeout" | "timeout_remove" | "kick" | "ban" | "demote" | "unban" | "delete_message" | "case_only";
+export type ModerationCaseSource = "staff_command" | "auto_moderation";
+export type ModerationCaseState = "pending" | "applied" | "failed" | "review" | "rejected" | "corrected" | "void";
+export type ModerationAttemptOutcome = "pending" | "succeeded" | "already_applied" | "failed" | "ambiguous" | "rejected" | "no_longer_required" | "member_missing" | "missing_permission" | "hierarchy_blocked" | "review_required";
+export type ModerationDeliveryState = "not_requested" | "pending" | "succeeded" | "failed" | "retry_pending" | "review_required";
+export declare const moderationDefaultPermissions: {
+    readonly module: {
+        readonly everyone: true;
+        readonly requiredPermissions: readonly [];
+        readonly allowedRoleIds: readonly [];
+        readonly deniedRoleIds: readonly [];
+        readonly allowedUserIds: readonly [];
+        readonly deniedUserIds: readonly [];
+    };
+    readonly commands: {
+        readonly "moderation.cases.read": {
+            readonly everyone: false;
+            readonly accessLevel: "administrator";
+            readonly requiredPermissions: readonly [];
+            readonly allowedRoleIds: readonly [];
+            readonly deniedRoleIds: readonly [];
+            readonly allowedUserIds: readonly [];
+            readonly deniedUserIds: readonly [];
+        };
+        readonly "moderation.cases.reconcile": {
+            readonly everyone: false;
+            readonly accessLevel: "administrator";
+            readonly requiredPermissions: readonly [];
+            readonly allowedRoleIds: readonly [];
+            readonly deniedRoleIds: readonly [];
+            readonly allowedUserIds: readonly [];
+            readonly deniedUserIds: readonly [];
+        };
+        readonly "moderation.cases.correct": {
+            readonly everyone: false;
+            readonly accessLevel: "administrator";
+            readonly requiredPermissions: readonly [];
+            readonly allowedRoleIds: readonly [];
+            readonly deniedRoleIds: readonly [];
+            readonly allowedUserIds: readonly [];
+            readonly deniedUserIds: readonly [];
+        };
+        readonly "moderation.cases.disassociate": {
+            readonly everyone: false;
+            readonly accessLevel: "administrator";
+            readonly requiredPermissions: readonly [];
+            readonly allowedRoleIds: readonly [];
+            readonly deniedRoleIds: readonly [];
+            readonly allowedUserIds: readonly [];
+            readonly deniedUserIds: readonly [];
+        };
+        readonly "moderation.private-notes": {
+            readonly everyone: false;
+            readonly accessLevel: "administrator";
+            readonly requiredPermissions: readonly [];
+            readonly allowedRoleIds: readonly [];
+            readonly deniedRoleIds: readonly [];
+            readonly allowedUserIds: readonly [];
+            readonly deniedUserIds: readonly [];
+        };
+        readonly "moderation.threads.act": {
+            readonly everyone: false;
+            readonly accessLevel: "administrator";
+            readonly requiredPermissions: readonly [];
+            readonly allowedRoleIds: readonly [];
+            readonly deniedRoleIds: readonly [];
+            readonly allowedUserIds: readonly [];
+            readonly deniedUserIds: readonly [];
+        };
+        readonly "moderation.threads.close": {
+            readonly everyone: false;
+            readonly accessLevel: "administrator";
+            readonly requiredPermissions: readonly [];
+            readonly allowedRoleIds: readonly [];
+            readonly deniedRoleIds: readonly [];
+            readonly allowedUserIds: readonly [];
+            readonly deniedUserIds: readonly [];
+        };
+        readonly "moderation.threads.close-delete": {
+            readonly everyone: false;
+            readonly accessLevel: "administrator";
+            readonly requiredPermissions: readonly [];
+            readonly allowedRoleIds: readonly [];
+            readonly deniedRoleIds: readonly [];
+            readonly allowedUserIds: readonly [];
+            readonly deniedUserIds: readonly [];
+        };
+        readonly "moderation.settings.manage": {
+            readonly everyone: false;
+            readonly accessLevel: "administrator";
+            readonly requiredPermissions: readonly [];
+            readonly allowedRoleIds: readonly [];
+            readonly deniedRoleIds: readonly [];
+            readonly allowedUserIds: readonly [];
+            readonly deniedUserIds: readonly [];
+        };
+    };
+};
+export declare const moderationLogging: {
+    events: {
+        id: string;
+        name: string;
+        description: string;
+        defaultEnabled: false;
+    }[];
+};
+//# sourceMappingURL=contracts.d.ts.map

package/dist/contracts.js

@@ -0,0 +1,84 @@
+import { MODERATION_CASE_ACTIONS, MODERATION_COMMAND_IDS, } from "./constants.js";
+const administrators = {
+    everyone: false,
+    accessLevel: "administrator",
+    requiredPermissions: [],
+    allowedRoleIds: [],
+    deniedRoleIds: [],
+    allowedUserIds: [],
+    deniedUserIds: [],
+};
+const everyone = {
+    everyone: true,
+    requiredPermissions: [],
+    allowedRoleIds: [],
+    deniedRoleIds: [],
+    allowedUserIds: [],
+    deniedUserIds: [],
+};
+export const moderationDefaultPermissions = {
+    module: everyone,
+    commands: {
+        ...Object.fromEntries(Object.values(MODERATION_COMMAND_IDS).map((id) => [id, administrators])),
+        ...Object.fromEntries(Object.values(MODERATION_CASE_ACTIONS).map((id) => [id, administrators])),
+        "moderation.cases.read": administrators,
+        "moderation.cases.reconcile": administrators,
+        "moderation.cases.correct": administrators,
+        "moderation.cases.disassociate": administrators,
+        "moderation.private-notes": administrators,
+        "moderation.threads.act": administrators,
+        "moderation.threads.close": administrators,
+        "moderation.threads.close-delete": administrators,
+        "moderation.settings.manage": administrators,
+    },
+};
+export const moderationLogging = {
+    events: [
+        [
+            "member-warned",
+            "Member warned",
+            "Records a warning without copying its reason or private note.",
+        ],
+        [
+            "member-timed-out",
+            "Member timed out",
+            "Records a timeout using case and duration metadata.",
+        ],
+        [
+            "member-kicked",
+            "Member kicked",
+            "Records a kick using case identifiers only.",
+        ],
+        [
+            "member-banned",
+            "Member banned",
+            "Records a ban using case identifiers and bounded deletion duration.",
+        ],
+        [
+            "member-demoted",
+            "Member demoted",
+            "Records a demotion using case and role identifiers.",
+        ],
+        [
+            "member-unbanned",
+            "Member unbanned",
+            "Records an unban using case identifiers only.",
+        ],
+        [
+            "member-unmuted",
+            "Member unmuted",
+            "Records timeout removal using case identifiers only.",
+        ],
+        [
+            "case-disassociated",
+            "Case user disassociated",
+            "Records that a case was detached from its user without retaining the former user identifier.",
+        ],
+    ].map(([id, name, description]) => ({
+        id: id,
+        name: name,
+        description: description,
+        defaultEnabled: false,
+    })),
+};
+//# sourceMappingURL=contracts.js.map

package/dist/domain.d.ts

@@ -0,0 +1,29 @@
+import type { ModerationBanDeleteMessageSeconds } from "@helyx/sdk";
+import type { ModerationAttemptOutcome, ModerationCaseState, ModerationDeliveryState } from "./contracts.js";
+export interface ModerationCaseStateSnapshot {
+    state: ModerationCaseState;
+    revision: number;
+    safeOutcome: string | null;
+    settledAt: Date | null;
+    disassociatedAt: Date | null;
+}
+export declare function validateReason(input: unknown): string;
+export declare function validatePrivateNote(input: unknown): string | undefined;
+export declare function validateTimeoutSeconds(input: unknown): number;
+export declare function validateBanDeleteMessageSeconds(input: unknown): ModerationBanDeleteMessageSeconds;
+export declare function validateDemotionRoleIds(input: unknown): string[];
+export declare function validateEvidenceReference(input: unknown): {
+    channelId: string;
+    messageId: string;
+} | undefined;
+export declare function caseOutcomeState(outcome: ModerationAttemptOutcome): Extract<ModerationCaseState, "pending" | "applied" | "failed" | "review" | "rejected">;
+export declare function transitionCase(current: ModerationCaseStateSnapshot, input: {
+    outcome: ModerationAttemptOutcome;
+    safeCode?: string;
+    at: Date;
+}): ModerationCaseStateSnapshot;
+export declare function canReconcileCase(state: ModerationCaseState): boolean;
+export declare function canCorrectCase(state: ModerationCaseState): boolean;
+export declare function disassociateCaseDomain(current: ModerationCaseStateSnapshot, at: Date): ModerationCaseStateSnapshot;
+export declare function threadDeliveryStateForAttempt(attempt: number, attemptLimit: number, retryable: boolean): ModerationDeliveryState;
+//# sourceMappingURL=domain.d.ts.map

package/dist/domain.js

@@ -0,0 +1,101 @@
+import { MODERATION_LIMITS } from "./constants.js";
+export function validateReason(input) {
+    if (typeof input !== "string")
+        throw new Error("A reason is required.");
+    const value = input.trim();
+    if (value.length < MODERATION_LIMITS.reasonMinCharacters ||
+        value.length > MODERATION_LIMITS.reasonMaxCharacters)
+        throw new Error("The reason must be between 10 and 500 characters.");
+    return value;
+}
+export function validatePrivateNote(input) {
+    if (input === undefined || input === null || input === "")
+        return undefined;
+    if (typeof input !== "string")
+        throw new Error("The private note is invalid.");
+    const value = input.trim();
+    if (!value || value.length > MODERATION_LIMITS.privateNoteMaxCharacters)
+        throw new Error("The private note must be no more than 1,000 characters.");
+    return value;
+}
+export function validateTimeoutSeconds(input) {
+    if (!Number.isInteger(input) ||
+        input < MODERATION_LIMITS.timeoutMinimumSeconds ||
+        input > MODERATION_LIMITS.timeoutMaximumSeconds)
+        throw new Error("Timeout duration must be between 1 minute and 28 days.");
+    return input;
+}
+const BAN_DELETE_MESSAGE_SECONDS = new Set([
+    0, 3_600, 21_600, 86_400, 259_200, 604_800,
+]);
+export function validateBanDeleteMessageSeconds(input) {
+    if (!Number.isInteger(input) ||
+        !BAN_DELETE_MESSAGE_SECONDS.has(input))
+        throw new Error("The ban message deletion duration is invalid.");
+    return input;
+}
+export function validateDemotionRoleIds(input) {
+    if (!Array.isArray(input) ||
+        input.length < 1 ||
+        input.length > MODERATION_LIMITS.demotionRoles ||
+        input.some((roleId) => typeof roleId !== "string" || !/^\d{17,20}$/u.test(roleId)))
+        throw new Error("Choose between 1 and 10 valid roles to remove.");
+    const unique = [...new Set(input)];
+    if (unique.length !== input.length)
+        throw new Error("Demotion roles must be unique.");
+    return unique;
+}
+export function validateEvidenceReference(input) {
+    if (input === undefined || input === null || input === "")
+        return undefined;
+    if (typeof input !== "string")
+        throw new Error("The message link is invalid.");
+    const match = /^https:\/\/discord(?:app)?\.com\/channels\/(\d{17,20})\/(\d{17,20})\/(\d{17,20})$/u.exec(input.trim());
+    if (!match?.[2] || !match[3])
+        throw new Error("The message link is invalid.");
+    return { channelId: match[2], messageId: match[3] };
+}
+export function caseOutcomeState(outcome) {
+    if (outcome === "pending")
+        return "pending";
+    if (outcome === "succeeded" ||
+        outcome === "already_applied" ||
+        outcome === "no_longer_required")
+        return "applied";
+    if (outcome === "ambiguous")
+        return "review";
+    if (outcome === "review_required")
+        return "review";
+    if (outcome === "rejected")
+        return "rejected";
+    return "failed";
+}
+export function transitionCase(current, input) {
+    if (current.state !== "pending" && current.state !== "review")
+        throw new Error("This moderation case cannot transition from its current state.");
+    const state = caseOutcomeState(input.outcome);
+    return {
+        ...current,
+        state,
+        revision: current.revision + 1,
+        safeOutcome: input.safeCode ?? input.outcome,
+        settledAt: state === "pending" || state === "review" ? null : input.at,
+    };
+}
+export function canReconcileCase(state) {
+    return state === "review" || state === "failed";
+}
+export function canCorrectCase(state) {
+    return state !== "pending" && state !== "corrected" && state !== "void";
+}
+export function disassociateCaseDomain(current, at) {
+    if (current.disassociatedAt)
+        return current;
+    return { ...current, revision: current.revision + 1, disassociatedAt: at };
+}
+export function threadDeliveryStateForAttempt(attempt, attemptLimit, retryable) {
+    if (!retryable)
+        return "review_required";
+    return attempt < attemptLimit ? "retry_pending" : "review_required";
+}
+//# sourceMappingURL=domain.js.map

package/dist/events.d.ts

@@ -0,0 +1,3 @@
+import { type EventContributions } from "@helyx/sdk";
+export declare function createModerationEvents(): EventContributions;
+//# sourceMappingURL=events.d.ts.map

package/dist/events.js

@@ -0,0 +1,60 @@
+import { HELYX_SERVICE_NAMES, } from "@helyx/sdk";
+import { MODERATION_MODULE_ID, MODERATION_TASK_KINDS } from "./constants.js";
+import { DEFAULT_MODERATION_CONFIGURATION, parseModerationConfiguration, } from "./configuration.js";
+export function createModerationEvents() {
+    return {
+        channelDelete: [
+            {
+                type: "discord.channel-delete",
+                execute: (context) => signalStructuralReconciliation(context.services, context.serverId, "channel", context.channelId),
+            },
+        ],
+        channelUpdate: [
+            {
+                type: "discord.channel-update",
+                execute: (context) => signalStructuralReconciliation(context.services, context.serverId, "channel", context.channelId),
+            },
+        ],
+        guildRoleDelete: [
+            {
+                type: "discord.guild-role-delete",
+                execute: (context) => signalStructuralReconciliation(context.services, context.serverId, "role", context.roleId),
+            },
+        ],
+        guildRoleUpdate: [
+            {
+                type: "discord.guild-role-update",
+                execute: (context) => signalStructuralReconciliation(context.services, context.serverId, "role", context.roleId),
+            },
+        ],
+    };
+}
+async function signalStructuralReconciliation(services, guildId, kind, resourceId) {
+    if (!services.has(HELYX_SERVICE_NAMES.scheduledTasks))
+        return;
+    const configuration = services.has(HELYX_SERVICE_NAMES.configuration)
+        ? await services
+            .get(HELYX_SERVICE_NAMES.configuration)
+            .get(guildId, MODERATION_MODULE_ID)
+        : null;
+    const settings = configuration
+        ? parseModerationConfiguration(configuration.value)
+        : DEFAULT_MODERATION_CONFIGURATION;
+    const relevant = kind === "channel"
+        ? settings.violationThreadChannelId === resourceId
+        : settings.violationAccessRoleId === resourceId ||
+            settings.violationModeratorRoleIds.includes(resourceId);
+    if (!relevant)
+        return;
+    await services
+        .get(HELYX_SERVICE_NAMES.scheduledTasks)
+        .signal({
+        moduleId: MODERATION_MODULE_ID,
+        taskKind: MODERATION_TASK_KINDS.threadAccessReconcile,
+        guildId,
+        coalesceKey: `guild:${guildId}`,
+        payload: {},
+        mode: "normal",
+    });
+}
+//# sourceMappingURL=events.js.map

package/dist/health.d.ts

@@ -0,0 +1,10 @@
+import type { HealthResult, RuntimeContext } from "@helyx/sdk";
+export declare class ModerationHealth {
+    #private;
+    start(context: RuntimeContext): void;
+    stop(): void;
+    recordTaskSuccess(taskKind: string): void;
+    recordTaskFailure(taskKind: string, safeCode: string): void;
+    snapshot(): HealthResult;
+}
+//# sourceMappingURL=health.d.ts.map

package/dist/health.js

@@ -0,0 +1,56 @@
+import { HELYX_SERVICE_NAMES } from "@helyx/sdk";
+const REQUIRED_SERVICES = [
+    HELYX_SERVICE_NAMES.records,
+    HELYX_SERVICE_NAMES.atomicModerationCases,
+    HELYX_SERVICE_NAMES.memberEnforcement,
+    HELYX_SERVICE_NAMES.memberRoleGrants,
+    HELYX_SERVICE_NAMES.messageEnforcement,
+    HELYX_SERVICE_NAMES.violationThreads,
+    HELYX_SERVICE_NAMES.scheduledTasks,
+    HELYX_SERVICE_NAMES.sessions,
+    HELYX_SERVICE_NAMES.secureRandom,
+    HELYX_SERVICE_NAMES.configuration,
+    HELYX_SERVICE_NAMES.audit,
+    HELYX_SERVICE_NAMES.resourceAuthorization,
+];
+export class ModerationHealth {
+    #running = false;
+    #missingServices = [];
+    #recoveryFailures = new Map();
+    start(context) {
+        this.#running = true;
+        this.#missingServices = REQUIRED_SERVICES.filter((service) => !context.services.has(service));
+        this.#recoveryFailures.clear();
+    }
+    stop() {
+        this.#running = false;
+        this.#missingServices = [];
+        this.#recoveryFailures.clear();
+    }
+    recordTaskSuccess(taskKind) {
+        this.#recoveryFailures.delete(taskKind);
+    }
+    recordTaskFailure(taskKind, safeCode) {
+        this.#recoveryFailures.set(taskKind, safeCode);
+    }
+    snapshot() {
+        if (!this.#running)
+            return { status: "unhealthy", message: "Moderation is stopped" };
+        if (this.#missingServices.length > 0)
+            return {
+                status: "unhealthy",
+                message: "Moderation runtime services are unavailable",
+            };
+        const safeCode = this.#recoveryFailures.values().next().value;
+        if (safeCode)
+            return {
+                status: "degraded",
+                message: `Moderation recovery requires attention (${safeCode})`,
+            };
+        return {
+            status: "healthy",
+            message: "Moderation case and recovery workflows are registered",
+        };
+    }
+}
+//# sourceMappingURL=health.js.map

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export declare const moderationModule: import("@helyx/sdk").ModuleDefinition;
+export default moderationModule;
+export * from "./configuration.js";
+export * from "./constants.js";
+export * from "./contracts.js";
+export * from "./domain.js";
+export * from "./records.js";
+export * from "./repository.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,92 @@
+import { readFileSync } from "node:fs";
+import { parseModuleManifest } from "@helyx/module-manifest";
+import { defineModule, getModulePrivacyDeclaration } from "@helyx/sdk";
+import { createModerationChannelActions } from "./channel-actions.js";
+import { createModerationCommands } from "./commands.js";
+import { createModerationInteractions } from "./components.js";
+import { parseModerationConfiguration } from "./configuration.js";
+import { moderationDefaultPermissions, moderationLogging, } from "./contracts.js";
+import { createModerationEvents } from "./events.js";
+import { ModerationHealth } from "./health.js";
+import { createModerationCasesResource } from "./moderation-cases-resource.js";
+import { createModerationPrivacyProvider } from "./privacy.js";
+import { createModerationActionProvider } from "./provider.js";
+import { moderationRecords } from "./records.js";
+import { ModerationService } from "./service.js";
+import { ModerationCaseActions } from "./case-actions.js";
+import { createModerationTasks, reconcileDashboardCase, reconcileModerationAction, } from "./tasks.js";
+import { ModerationThreadControls } from "./thread-controls.js";
+import { ModerationThreadDelivery } from "./thread-delivery.js";
+const manifest = parseModuleManifest(JSON.parse(readFileSync(new URL("../manifest.json", import.meta.url), "utf8")));
+const service = new ModerationService();
+const threadDelivery = new ModerationThreadDelivery();
+const threadControls = new ModerationThreadControls(service);
+const health = new ModerationHealth();
+service.attachThreadRuntime(threadDelivery);
+const componentInteractions = createModerationInteractions(service, threadControls);
+const tasks = createModerationTasks({
+    deliverPendingThread: (services, input) => threadDelivery.deliverPending(services, input),
+    reconcileAction: (services, input) => reconcileModerationAction(services, input),
+    reconcileThreadAccess: (services, input) => threadDelivery.reconcileAccess(services, input.guildId),
+}, health);
+export const moderationModule = defineModule({
+    manifest,
+    configuration: {
+        schemaVersion: 1,
+        validate: (input) => ({ ...parseModerationConfiguration(input) }),
+    },
+    defaultPermissions: moderationDefaultPermissions,
+    permissionOperations: Object.entries(moderationDefaultPermissions.commands)
+        .filter(([id]) => id.startsWith("moderation.cases.") ||
+        id.startsWith("moderation.threads.") ||
+        id === "moderation.private-notes" ||
+        id === "moderation.settings.manage")
+        .map(([id]) => ({ id, name: id, description: `Authorises ${id}.` })),
+    records: moderationRecords,
+    interactions: {
+        commands: createModerationCommands(service),
+        buttons: componentInteractions.buttons ?? [],
+        ...(componentInteractions.modals
+            ? { modals: componentInteractions.modals }
+            : {}),
+        ...(componentInteractions.selects
+            ? { selects: componentInteractions.selects }
+            : {}),
+    },
+    events: createModerationEvents(),
+    logging: moderationLogging,
+    privacy: {
+        providerVersion: 1,
+        create: (executor, services) => createModerationPrivacyProvider({
+            id: manifest.id,
+            declaration: getModulePrivacyDeclaration(manifest),
+            executor,
+            ...(services ? { services } : {}),
+        }),
+    },
+    scheduledTasks: tasks,
+    managedResources: [
+        createModerationCasesResource({ reconcileCase: reconcileDashboardCase }, new ModerationCaseActions(service)),
+    ],
+    dashboardActions: createModerationChannelActions(),
+    moderationActionProvider: createModerationActionProvider(service),
+    start(context) {
+        health.start(context);
+        context.logger.info({ event: "moderation.started" }, "Moderation module started");
+        return Promise.resolve();
+    },
+    stop(context) {
+        health.stop();
+        context.logger.info({ event: "moderation.stopped" }, "Moderation module stopped");
+        return Promise.resolve();
+    },
+    health: () => health.snapshot(),
+});
+export default moderationModule;
+export * from "./configuration.js";
+export * from "./constants.js";
+export * from "./contracts.js";
+export * from "./domain.js";
+export * from "./records.js";
+export * from "./repository.js";
+//# sourceMappingURL=index.js.map

package/dist/moderation-cases-resource.d.ts

@@ -0,0 +1,14 @@
+import { type ModuleManagedResource, type ServiceAccess } from "@helyx/sdk";
+import type { ModerationCaseActions } from "./case-actions.js";
+export interface ModerationCaseResourceReconciler {
+    reconcileCase(input: {
+        guildId: string;
+        caseId: string;
+        expectedRevision: number;
+        actorUserId: string;
+        operationKey: string;
+        services: ServiceAccess;
+    }): Promise<void>;
+}
+export declare function createModerationCasesResource(reconciler: ModerationCaseResourceReconciler, caseActions?: Pick<ModerationCaseActions, "execute">): ModuleManagedResource;
+//# sourceMappingURL=moderation-cases-resource.d.ts.map