@helyx/module-moderation 1.0.1

package/dist/moderation-cases-resource.js

@@ -0,0 +1,226 @@
+import { DashboardActionValidationError, HELYX_SERVICE_NAMES, } from "@helyx/sdk";
+import { MODERATION_CASE_ACTIONS, MODERATION_MODULE_ID } from "./constants.js";
+import { validateReason } from "./domain.js";
+import { moderationCaseDetail, moderationCaseSummary } from "./presentation.js";
+import { ModerationRepository, } from "./repository.js";
+export function createModerationCasesResource(reconciler, caseActions) {
+    return {
+        id: "moderation-cases",
+        list: async (context, input) => {
+            const repository = new ModerationRepository(context.services);
+            const page = await repository.listCases(caseQuery(context.guildId, input));
+            return {
+                items: page.items.map(moderationCaseSummary),
+                ...(page.nextCursor ? { nextCursor: page.nextCursor } : {}),
+            };
+        },
+        read: async (context, resourceId) => {
+            const item = await new ModerationRepository(context.services).findCase(context.guildId, resourceId);
+            return item
+                ? caseDetail(new ModerationRepository(context.services), item, false)
+                : null;
+        },
+        preview: () => unsupported("Cases cannot be previewed."),
+        create: () => unsupported("Cases are created by moderation actions."),
+        update: () => unsupported("Applied cases cannot be edited."),
+        delete: () => unsupported("Moderation cases cannot be deleted."),
+        executeAction: async (context, input) => {
+            const repository = new ModerationRepository(context.services);
+            const current = await repository.findCase(context.guildId, input.resourceId);
+            if (!current)
+                return null;
+            if (current.revision !== input.expectedRevision)
+                throw validation("This case changed in another session.");
+            if (Object.hasOwn(MODERATION_CASE_ACTIONS, input.actionId)) {
+                if (!caseActions)
+                    throw validation("Moderation case actions are temporarily unavailable.");
+                await caseActions.execute(context, current, input.actionId, input.value);
+                return refreshedCase(repository, current, false);
+            }
+            const operationKey = `dashboard:${input.actionId}:${context.correlationId}:${current.caseId}`;
+            if (input.actionId === "reconcile") {
+                await reconciler.reconcileCase({
+                    guildId: context.guildId,
+                    caseId: current.caseId,
+                    expectedRevision: current.revision,
+                    actorUserId: context.actor.userId,
+                    operationKey,
+                    services: context.services,
+                });
+                return refreshedCase(repository, current, false);
+            }
+            if (input.actionId === "correct") {
+                const result = await atomic(context.services).createCorrectionCase({
+                    operationKey,
+                    guildId: context.guildId,
+                    caseId: current.caseId,
+                    expectedRevision: current.revision,
+                    actorUserId: context.actor.userId,
+                    reason: validateReason(input.value.correctionReason),
+                    occurredAt: new Date(),
+                });
+                if (result.outcome === "rejected")
+                    throw validation(actionFailure(result.code));
+                return refreshedCase(repository, current, false);
+            }
+            if (input.actionId === "disassociate") {
+                const result = await atomic(context.services).disassociateCase({
+                    operationKey,
+                    guildId: context.guildId,
+                    caseId: current.caseId,
+                    expectedRevision: current.revision,
+                    actorUserId: context.actor.userId,
+                    occurredAt: new Date(),
+                });
+                if (result.outcome === "rejected")
+                    throw validation(actionFailure(result.code));
+                return refreshedCase(repository, current, false);
+            }
+            if (input.actionId === "reveal-private-note") {
+                await audit(context.services, {
+                    guildId: context.guildId,
+                    actorUserId: context.actor.userId,
+                    action: "moderation.case.private-note-revealed",
+                    correlationId: context.correlationId,
+                    idempotencyKey: operationKey,
+                    targetId: current.caseId,
+                });
+                return caseDetail(repository, current, true);
+            }
+            throw validation("Unknown moderation case action.");
+        },
+    };
+}
+async function refreshedCase(repository, previous, revealPrivateNote) {
+    const refreshed = await repository.findCase(previous.guildId, previous.caseId);
+    if (!refreshed)
+        throw validation("The updated case is unavailable.");
+    return caseDetail(repository, refreshed, revealPrivateNote);
+}
+async function caseDetail(repository, item, revealPrivateNote) {
+    const delivery = await repository.findThreadDelivery(item.guildId, item.caseId);
+    const availableActionIds = ["correct", "disassociate", "reveal-private-note"];
+    if (item.state === "failed" ||
+        item.state === "review" ||
+        (delivery &&
+            (delivery.caseRevision !== item.revision ||
+                delivery.safeCode?.startsWith("thread_control_ambiguous_"))))
+        availableActionIds.push("reconcile");
+    if (item.state === "applied" &&
+        item.subjectUserId &&
+        !item.disassociatedAt &&
+        (!delivery || delivery.caseRevision === item.revision) &&
+        (delivery?.resolutionState !== "closed" ||
+            delivery.closeState === "succeeded")) {
+        if (delivery?.resolutionState === "closed")
+            availableActionIds.push("close-and-delete-thread");
+        else if (delivery?.resolutionState === "resolved")
+            availableActionIds.push("close-thread", "close-and-delete-thread");
+        else {
+            availableActionIds.push("mute", "unmute", "kick", "ban", "demote");
+            if (delivery)
+                availableActionIds.push("no-further-action");
+        }
+    }
+    const detail = moderationCaseDetail(item, { revealPrivateNote });
+    return {
+        ...detail,
+        availableActionIds,
+        value: {
+            ...detail.value,
+            privateNoteState: item.privateNote
+                ? revealPrivateNote
+                    ? "Revealed"
+                    : "Hidden — use Reveal private note"
+                : "No private note recorded",
+            threadState: delivery?.resolutionState ?? "No violation thread",
+        },
+    };
+}
+function caseQuery(guildId, input) {
+    const filters = input.filters ?? {};
+    const repeatOrdinal = optionalOrdinal(filters.repeatOrdinal);
+    const from = optionalDate(filters.from, "From");
+    const to = optionalDate(filters.to, "To");
+    return {
+        guildId,
+        limit: input.limit,
+        ...(input.cursor ? { cursor: input.cursor } : {}),
+        ...(input.search?.trim() ? { search: input.search.trim() } : {}),
+        ...(filters.actorUserId?.trim()
+            ? { actorUserId: filters.actorUserId.trim() }
+            : {}),
+        ...(filters.ruleId?.trim() ? { ruleId: filters.ruleId.trim() } : {}),
+        ...(repeatOrdinal ? { repeatOrdinal } : {}),
+        ...(isAction(filters.action) ? { action: filters.action } : {}),
+        ...(isState(filters.state) ? { state: filters.state } : {}),
+        ...(from ? { from } : {}),
+        ...(to ? { to } : {}),
+    };
+}
+function atomic(services) {
+    return services.get(HELYX_SERVICE_NAMES.atomicModerationCases);
+}
+async function audit(services, input) {
+    await services.get(HELYX_SERVICE_NAMES.audit).append({
+        ...input,
+        source: "dashboard",
+        moduleId: MODERATION_MODULE_ID,
+        targetType: "moderation-case",
+    });
+}
+function actionFailure(code) {
+    if (code === "not_found")
+        return "This case no longer exists.";
+    if (code === "revision_conflict")
+        return "This case changed in another session.";
+    if (code === "case_not_correctable")
+        return "This case cannot be corrected in its current state.";
+    return "The case action could not be completed safely.";
+}
+function optionalDate(value, label) {
+    if (!value)
+        return undefined;
+    const parsed = new Date(value);
+    if (!Number.isFinite(parsed.getTime()))
+        throw validation(`${label} must be a valid date.`);
+    return parsed;
+}
+function optionalOrdinal(value) {
+    if (!value)
+        return undefined;
+    if (value === "1" || value === "2" || value === "3")
+        return Number(value);
+    throw validation("Offence must be first, second or third and later.");
+}
+function isAction(value) {
+    return [
+        "warn",
+        "timeout",
+        "timeout_remove",
+        "kick",
+        "ban",
+        "demote",
+        "unban",
+        "delete_message",
+        "case_only",
+    ].includes(value ?? "");
+}
+function isState(value) {
+    return [
+        "pending",
+        "applied",
+        "failed",
+        "review",
+        "rejected",
+        "corrected",
+        "void",
+    ].includes(value ?? "");
+}
+function unsupported(message) {
+    throw validation(message);
+}
+function validation(message) {
+    return new DashboardActionValidationError(message);
+}
+//# sourceMappingURL=moderation-cases-resource.js.map

package/dist/presentation.d.ts

@@ -0,0 +1,8 @@
+import type { ManagedResourceDetail, ManagedResourceSummary, MessageResponse } from "@helyx/sdk";
+import type { StoredModerationCase } from "./repository.js";
+export declare function moderationCaseSummary(item: StoredModerationCase): ManagedResourceSummary;
+export declare function moderationCaseDetail(item: StoredModerationCase, options?: {
+    revealPrivateNote?: boolean;
+}): ManagedResourceDetail;
+export declare function moderationEphemeral(title: string, description: string): MessageResponse;
+//# sourceMappingURL=presentation.d.ts.map

package/dist/presentation.js

@@ -0,0 +1,69 @@
+import { formatModerationCaseNumber } from "./case-naming.js";
+export function moderationCaseSummary(item) {
+    return {
+        id: item.caseId,
+        revision: item.revision,
+        status: item.state,
+        title: `Case #${formatModerationCaseNumber(item.caseNumber)}`,
+        description: `${actionLabel(item.action)} · ${sourceLabel(item.source)}`,
+        attributes: {
+            subjectUserId: item.subjectUserId ?? "Disassociated",
+            actorUserId: item.actorUserId ?? "Unavailable",
+            action: actionLabel(item.action),
+            repeatOrdinal: item.repeatOffenceOrdinal
+                ? ordinalLabel(item.repeatOffenceOrdinal)
+                : "Not a repeat ladder",
+        },
+        updatedAt: item.updatedAt.toISOString(),
+    };
+}
+export function moderationCaseDetail(item, options = {}) {
+    const summary = moderationCaseSummary(item);
+    return {
+        ...summary,
+        value: {
+            caseNumber: item.caseNumber,
+            subjectUserId: item.subjectUserId,
+            actorUserId: item.actorUserId,
+            action: actionLabel(item.action),
+            reason: item.reason,
+            privateNote: options.revealPrivateNote ? item.privateNote : null,
+            source: sourceLabel(item.source),
+            state: stateLabel(item.state),
+            safeOutcome: item.safeOutcome,
+            repeatOrdinal: item.repeatOffenceOrdinal,
+            relatedCaseId: item.relatedCaseId,
+            createdAt: item.createdAt.toISOString(),
+            settledAt: item.settledAt?.toISOString() ?? null,
+            disassociatedAt: item.disassociatedAt?.toISOString() ?? null,
+            retentionExpiresAt: item.retentionExpiresAt?.toISOString() ?? null,
+            retentionProcessedAt: item.retentionProcessedAt?.toISOString() ?? null,
+        },
+    };
+}
+export function moderationEphemeral(title, description) {
+    return {
+        ephemeral: true,
+        embed: { title, description, color: 0x7c3aed },
+        allowedUserMentionIds: [],
+    };
+}
+function actionLabel(action) {
+    if (action === "timeout_remove")
+        return "Timeout removed";
+    if (action === "delete_message")
+        return "Message deleted";
+    if (action === "case_only")
+        return "Case only";
+    return action.charAt(0).toUpperCase() + action.slice(1);
+}
+function sourceLabel(source) {
+    return source === "staff_command" ? "Staff command" : "Auto Moderation";
+}
+function stateLabel(state) {
+    return state.charAt(0).toUpperCase() + state.slice(1).replaceAll("_", " ");
+}
+function ordinalLabel(ordinal) {
+    return ordinal === 1 ? "First" : ordinal === 2 ? "Second" : "Third or later";
+}
+//# sourceMappingURL=presentation.js.map

package/dist/privacy.d.ts

@@ -0,0 +1,8 @@
+import { type PrivacyProvider, type PrivacyProviderExecutor, type ServiceAccess } from "@helyx/sdk";
+export declare function createModerationPrivacyProvider(input: {
+    id: string;
+    declaration: ReturnType<PrivacyProvider["describe"]>;
+    executor: PrivacyProviderExecutor;
+    services?: ServiceAccess;
+}): PrivacyProvider;
+//# sourceMappingURL=privacy.d.ts.map

package/dist/privacy.js

@@ -0,0 +1,38 @@
+import { HELYX_SERVICE_NAMES, createPrivacyProvider, } from "@helyx/sdk";
+export function createModerationPrivacyProvider(input) {
+    const generic = createPrivacyProvider({
+        id: input.id,
+        declaration: input.declaration,
+        executor: input.executor,
+    });
+    const indirect = getIndirectService(input.services);
+    return {
+        id: generic.id,
+        version: generic.version,
+        describe: () => generic.describe(),
+        captureAccess: (request) => indirect
+            ? indirect.captureAccess(request)
+            : Promise.resolve({
+                outcome: "manual_review",
+                items: [],
+            }),
+        erase: (request) => indirect
+            ? indirect.erase(request)
+            : Promise.resolve({
+                outcome: "manual_review",
+                results: input.declaration.collections.map(({ name }) => ({
+                    collection: name,
+                    outcome: "manual_review",
+                    affectedRecords: 0,
+                    reasonCode: "moderation_privacy_service_unavailable",
+                })),
+            }),
+        assessCorrection: (request) => generic.assessCorrection(request),
+    };
+}
+function getIndirectService(services) {
+    if (!services?.has(HELYX_SERVICE_NAMES.moderationCasePrivacy))
+        return null;
+    return services.get(HELYX_SERVICE_NAMES.moderationCasePrivacy);
+}
+//# sourceMappingURL=privacy.js.map

package/dist/provider.d.ts

@@ -0,0 +1,4 @@
+import { type ModerationActionProviderContributionV2 } from "@helyx/sdk";
+import type { ModerationService } from "./service.js";
+export declare function createModerationActionProvider(runtime: Pick<ModerationService, "dispatchAction" | "deliverViolationThread">): ModerationActionProviderContributionV2;
+//# sourceMappingURL=provider.d.ts.map