@helyx/module-automod 1.0.1

package/dist/repository.js

@@ -0,0 +1,523 @@
+import { HELYX_SERVICE_NAMES, } from "@helyx/sdk";
+import { randomUUID } from "node:crypto";
+import { AUTOMOD_LIMITS, AUTOMOD_MODULE_ID } from "./constants.js";
+import { RECEIPT_FIELDS, RULE_FIELDS, mapReceipt, mapRule, } from "./repository-model.js";
+export class AutoModerationRepository {
+    #records;
+    constructor(services) {
+        this.#records = isServiceAccess(services)
+            ? services.get(HELYX_SERVICE_NAMES.records)
+            : services;
+    }
+    async listRules(input) {
+        if (!Number.isInteger(input.limit) ||
+            input.limit < 1 ||
+            input.limit > AUTOMOD_LIMITS.rulePageSize)
+            throw new Error("Auto Moderation rule page size is invalid.");
+        const page = await this.#records.findMany({
+            moduleId: AUTOMOD_MODULE_ID,
+            collection: "rules",
+            select: RULE_FIELDS,
+            where: {
+                guild_id: input.guildId,
+                ...(input.status ? { status: input.status } : {}),
+            },
+            orderBy: [
+                { field: "updated_at", direction: "desc" },
+                { field: "rule_id", direction: "desc" },
+            ],
+            ...(input.cursor ? { cursor: input.cursor } : {}),
+            ...(input.search ? { search: input.search } : {}),
+            limit: input.limit,
+        });
+        return { items: page.records.map(mapRule), nextCursor: page.nextCursor };
+    }
+    async findRule(guildId, ruleId) {
+        const row = await this.#records.findOne({
+            moduleId: AUTOMOD_MODULE_ID,
+            collection: "rules",
+            select: RULE_FIELDS,
+            where: { guild_id: guildId, rule_id: ruleId },
+        });
+        return row ? mapRule(row) : null;
+    }
+    async findByNativeRuleId(guildId, nativeRuleId) {
+        const row = await this.#records.findOne({
+            moduleId: AUTOMOD_MODULE_ID,
+            collection: "rules",
+            select: RULE_FIELDS,
+            where: { guild_id: guildId, native_rule_id: nativeRuleId },
+        });
+        return row ? mapRule(row) : null;
+    }
+    async listPublishedGuildIds(limit = 5_000) {
+        const guildIds = [];
+        let after;
+        while (guildIds.length < limit) {
+            const pageLimit = Math.min(25, limit - guildIds.length);
+            const groups = await this.#records.groupCount({
+                moduleId: AUTOMOD_MODULE_ID,
+                collection: "rules",
+                where: { status: "published" },
+                groupBy: "guild_id",
+                ...(after ? { after } : {}),
+                limit: pageLimit,
+            });
+            const page = groups
+                .map(({ value }) => value)
+                .filter((value) => typeof value === "string");
+            guildIds.push(...page);
+            if (page.length < pageLimit)
+                break;
+            after = page.at(-1);
+            if (!after)
+                break;
+        }
+        return guildIds;
+    }
+    async listAllPublishedRules(guildId) {
+        const items = [];
+        let cursor;
+        do {
+            const page = await this.listRules({
+                guildId,
+                status: "published",
+                limit: AUTOMOD_LIMITS.rulePageSize,
+                ...(cursor ? { cursor } : {}),
+            });
+            items.push(...page.items);
+            cursor = page.nextCursor ?? undefined;
+        } while (cursor);
+        return items;
+    }
+    async createDraft(input) {
+        const ruleId = input.ruleId ?? randomUUID();
+        const operationKey = `automod:${ruleId}:1`;
+        const result = await this.#records.appendUnique({
+            moduleId: AUTOMOD_MODULE_ID,
+            collection: "rules",
+            values: {
+                rule_id: ruleId,
+                guild_id: input.guildId,
+                name: input.draft.name,
+                name_key: input.draft.name.toLocaleLowerCase("en"),
+                category: input.draft.category,
+                rule_kind: input.draft.kind,
+                status: "draft",
+                document_json: JSON.stringify(input.draft),
+                operation_key: operationKey,
+                configuration_revision: "0",
+                revision: 1,
+                created_by_user_id: input.actorUserId,
+                updated_by_user_id: input.actorUserId,
+                created_at: input.occurredAt,
+                updated_at: input.occurredAt,
+            },
+            uniqueBy: ["guild_id", "name_key"],
+            quotaGuards: [
+                {
+                    collection: "rules",
+                    where: { guild_id: input.guildId },
+                    maximum: AUTOMOD_LIMITS.rulesPerGuild,
+                },
+            ],
+            audit: audit(input.guildId, input.actorUserId, "automod.rule-created", ruleId, operationKey),
+        });
+        if (!result.created)
+            throw new Error("An Auto Moderation rule with this name already exists.");
+        return {
+            ruleId,
+            guildId: input.guildId,
+            name: input.draft.name,
+            category: input.draft.category,
+            kind: input.draft.kind,
+            status: "draft",
+            draft: input.draft,
+            nativeRuleId: null,
+            nativeFingerprint: null,
+            operationKey,
+            configurationRevision: "0",
+            revision: 1,
+            createdByUserId: input.actorUserId,
+            updatedByUserId: input.actorUserId,
+            createdAt: input.occurredAt,
+            updatedAt: input.occurredAt,
+        };
+    }
+    async updateRule(input) {
+        const nextRevision = input.current.revision + 1;
+        const draft = input.draft ?? input.current.draft;
+        const updated = await this.#records.updateOne({
+            moduleId: AUTOMOD_MODULE_ID,
+            collection: "rules",
+            where: { guild_id: input.current.guildId, rule_id: input.current.ruleId },
+            expected: { field: "revision", value: input.current.revision },
+            values: {
+                name: draft.name,
+                name_key: draft.name.toLocaleLowerCase("en"),
+                category: draft.category,
+                rule_kind: draft.kind,
+                document_json: JSON.stringify(draft),
+                status: input.status ?? input.current.status,
+                native_rule_id: input.nativeRuleId === undefined
+                    ? input.current.nativeRuleId
+                    : input.nativeRuleId,
+                native_fingerprint: input.nativeFingerprint === undefined
+                    ? input.current.nativeFingerprint
+                    : input.nativeFingerprint,
+                configuration_revision: input.configurationRevision ?? input.current.configurationRevision,
+                operation_key: `automod:${input.current.ruleId}:${nextRevision}`,
+                revision: nextRevision,
+                updated_by_user_id: input.actorUserId,
+                updated_at: input.occurredAt,
+            },
+            audit: audit(input.current.guildId, input.actorUserId ?? undefined, input.action, input.current.ruleId, `automod:${input.current.ruleId}:${nextRevision}`),
+        });
+        if (!updated.updated)
+            return null;
+        return {
+            ...input.current,
+            name: draft.name,
+            category: draft.category,
+            kind: draft.kind,
+            draft,
+            status: input.status ?? input.current.status,
+            nativeRuleId: input.nativeRuleId === undefined
+                ? input.current.nativeRuleId
+                : input.nativeRuleId,
+            nativeFingerprint: input.nativeFingerprint === undefined
+                ? input.current.nativeFingerprint
+                : input.nativeFingerprint,
+            configurationRevision: input.configurationRevision ?? input.current.configurationRevision,
+            operationKey: `automod:${input.current.ruleId}:${nextRevision}`,
+            revision: nextRevision,
+            updatedByUserId: input.actorUserId,
+            updatedAt: input.occurredAt,
+        };
+    }
+    deleteDraft(input) {
+        return this.#records.deleteOne({
+            moduleId: AUTOMOD_MODULE_ID,
+            collection: "rules",
+            where: { guild_id: input.current.guildId, rule_id: input.current.ruleId },
+            expected: { field: "revision", value: input.current.revision },
+            audit: audit(input.current.guildId, input.actorUserId, "automod.rule-draft-deleted", input.current.ruleId, `${input.current.operationKey}:delete`),
+        });
+    }
+    async appendReceipt(input) {
+        const receiptId = randomUUID();
+        const retentionExpiresAt = addDays(input.occurredAt, AUTOMOD_LIMITS.actionReceiptRetentionDays);
+        return this.#records.appendUnique({
+            moduleId: AUTOMOD_MODULE_ID,
+            collection: "action_receipts",
+            values: {
+                receipt_id: receiptId,
+                guild_id: input.guildId,
+                event_key: input.eventKey,
+                rule_id: input.rule.ruleId,
+                rule_revision: input.rule.revision,
+                configuration_revision: input.rule.configurationRevision,
+                native_rule_id: input.nativeRuleId,
+                source: "native",
+                subject_user_id: input.subjectUserId,
+                ...(input.channelId ? { channel_id: input.channelId } : {}),
+                ...(input.messageId ? { message_id: input.messageId } : {}),
+                ...(input.alertSystemMessageId
+                    ? { alert_system_message_id: input.alertSystemMessageId }
+                    : {}),
+                action_type: input.actionType,
+                claim_key: input.claimKey,
+                outcome: "observed",
+                occurred_at: input.occurredAt,
+                retention_expires_at: retentionExpiresAt,
+                created_at: new Date(),
+            },
+            uniqueBy: ["guild_id", "event_key"],
+            retention: [
+                {
+                    collection: "action_receipts",
+                    where: { guild_id: input.guildId, receipt_id: receiptId },
+                    scheduledFor: retentionExpiresAt,
+                    idempotencyKey: `receipt:${receiptId}`,
+                },
+            ],
+        });
+    }
+    async appendEnhancedReceipt(input) {
+        const { result } = input;
+        const receiptId = randomUUID();
+        const retentionExpiresAt = addDays(input.occurredAt, AUTOMOD_LIMITS.actionReceiptRetentionDays);
+        return this.#records.appendUnique({
+            moduleId: AUTOMOD_MODULE_ID,
+            collection: "action_receipts",
+            values: {
+                receipt_id: receiptId,
+                guild_id: result.guildId,
+                event_key: result.operationId,
+                rule_id: input.rule.ruleId,
+                rule_revision: input.rule.revision,
+                configuration_revision: input.rule.configurationRevision,
+                source: "enhanced",
+                detector_version: result.detectorVersion,
+                scoring_version: result.scoringVersion,
+                term_id: result.termId,
+                detection_method: result.method,
+                confidence_class: result.confidenceClass,
+                confidence_score: result.confidenceScore,
+                effective_threshold: result.effectiveThreshold,
+                correlation_id: result.correlationId,
+                subject_user_id: result.authorUserId,
+                channel_id: result.channelId,
+                message_id: result.messageId,
+                action_type: "detection",
+                claim_key: input.claimKey,
+                outcome: "observed",
+                occurred_at: input.occurredAt,
+                retention_expires_at: retentionExpiresAt,
+                created_at: new Date(),
+            },
+            uniqueBy: ["guild_id", "event_key"],
+            retention: [
+                {
+                    collection: "action_receipts",
+                    where: { guild_id: result.guildId, receipt_id: receiptId },
+                    scheduledFor: retentionExpiresAt,
+                    idempotencyKey: `receipt:${receiptId}`,
+                },
+            ],
+        });
+    }
+    async settleReceipt(input) {
+        await this.#records.updateOne({
+            moduleId: AUTOMOD_MODULE_ID,
+            collection: "action_receipts",
+            where: { guild_id: input.guildId, event_key: input.eventKey },
+            expected: { field: "outcome", value: "observed" },
+            values: {
+                outcome: input.outcome,
+                moderation_case_id: input.moderationCaseId ?? null,
+                safe_code: input.safeCode ?? null,
+            },
+        });
+    }
+    async findReceiptByEventKey(input) {
+        const current = await this.#records.findOne({
+            moduleId: AUTOMOD_MODULE_ID,
+            collection: "action_receipts",
+            select: ["outcome", "moderation_case_id", "safe_code"],
+            where: { guild_id: input.guildId, event_key: input.eventKey },
+        });
+        if (!current || typeof current.outcome !== "string")
+            return null;
+        return {
+            outcome: current.outcome,
+            moderationCaseId: typeof current.moderation_case_id === "string"
+                ? current.moderation_case_id
+                : null,
+            safeCode: typeof current.safe_code === "string" ? current.safe_code : null,
+        };
+    }
+    async claimEnforcement(input) {
+        // Pending claims are deliberately not scheduled for deletion. They may
+        // represent an interrupted enforcement hand-off and must remain available
+        // for reconciliation until they reach a terminal outcome.
+        const retentionExpiresAt = addDays(input.occurredAt, AUTOMOD_LIMITS.settledClaimRetentionDays);
+        const result = await this.#records.appendUnique({
+            moduleId: AUTOMOD_MODULE_ID,
+            collection: "enforcement_claims",
+            values: {
+                claim_key: input.claimKey,
+                guild_id: input.guildId,
+                rule_id: input.rule.ruleId,
+                rule_revision: input.rule.revision,
+                configuration_revision: input.rule.configurationRevision,
+                subject_user_id: input.subjectUserId,
+                ...(input.channelId ? { channel_id: input.channelId } : {}),
+                ...(input.messageId ? { message_id: input.messageId } : {}),
+                category: input.rule.category,
+                action_family: input.actionFamily,
+                source: input.source,
+                request_fingerprint: input.requestFingerprint,
+                outcome: "pending",
+                revision: 1,
+                occurred_at: input.occurredAt,
+                retention_expires_at: retentionExpiresAt,
+                created_at: new Date(),
+                updated_at: new Date(),
+            },
+            uniqueBy: ["guild_id", "claim_key"],
+        });
+        if (result.created)
+            return {
+                created: true,
+                conflict: false,
+                source: input.source,
+                outcome: "pending",
+                moderationCaseId: null,
+                repeatOrdinal: null,
+                selectedAction: null,
+                safeCode: null,
+            };
+        const current = await this.#records.findOne({
+            moduleId: AUTOMOD_MODULE_ID,
+            collection: "enforcement_claims",
+            select: [
+                "request_fingerprint",
+                "source",
+                "outcome",
+                "moderation_case_id",
+                "repeat_ordinal",
+                "selected_action",
+                "safe_code",
+            ],
+            where: { guild_id: input.guildId, claim_key: input.claimKey },
+        });
+        return {
+            created: false,
+            conflict: !current || current.request_fingerprint !== input.requestFingerprint,
+            source: current?.source ?? input.source,
+            outcome: typeof current?.outcome === "string" ? current.outcome : "pending",
+            moderationCaseId: typeof current?.moderation_case_id === "string"
+                ? current.moderation_case_id
+                : null,
+            repeatOrdinal: typeof current?.repeat_ordinal === "number"
+                ? current.repeat_ordinal
+                : null,
+            selectedAction: typeof current?.selected_action === "string"
+                ? current.selected_action
+                : null,
+            safeCode: typeof current?.safe_code === "string" ? current.safe_code : null,
+        };
+    }
+    async disassociateCaseLinks(input) {
+        let detachedRecords = 0;
+        for (const collection of [
+            "action_receipts",
+            "enforcement_claims",
+        ]) {
+            const idField = collection === "action_receipts" ? "receipt_id" : "claim_key";
+            let cursor;
+            do {
+                const page = await this.#records.findMany({
+                    moduleId: AUTOMOD_MODULE_ID,
+                    collection,
+                    select: [idField, "guild_id", "subject_user_id", "occurred_at"],
+                    where: {
+                        guild_id: input.guildId,
+                        moderation_case_id: input.moderationCaseId,
+                    },
+                    orderBy: [
+                        { field: "occurred_at", direction: "desc" },
+                        ...(collection === "enforcement_claims"
+                            ? [{ field: "guild_id", direction: "desc" }]
+                            : []),
+                        { field: idField, direction: "desc" },
+                    ],
+                    limit: 100,
+                    ...(cursor ? { cursor } : {}),
+                });
+                for (const row of page.records) {
+                    if (typeof row.subject_user_id !== "string")
+                        continue;
+                    const recordId = row[idField];
+                    if (typeof recordId !== "string")
+                        continue;
+                    const updated = await this.#records.updateOne({
+                        moduleId: AUTOMOD_MODULE_ID,
+                        collection,
+                        where: collection === "action_receipts"
+                            ? { receipt_id: recordId }
+                            : { guild_id: input.guildId, claim_key: recordId },
+                        expected: {
+                            field: "subject_user_id",
+                            value: row.subject_user_id,
+                        },
+                        values: { subject_user_id: null },
+                    });
+                    if (updated.updated)
+                        detachedRecords += 1;
+                }
+                cursor = page.nextCursor ?? undefined;
+            } while (cursor);
+        }
+        return { detachedRecords };
+    }
+    async settleClaim(input) {
+        const retentionExpiresAt = addDays(input.occurredAt, AUTOMOD_LIMITS.settledClaimRetentionDays);
+        await this.#records.updateOne({
+            moduleId: AUTOMOD_MODULE_ID,
+            collection: "enforcement_claims",
+            where: { guild_id: input.guildId, claim_key: input.claimKey },
+            expected: { field: "revision", value: 1 },
+            values: {
+                moderation_case_id: input.moderationCaseId ?? null,
+                repeat_ordinal: input.repeatOrdinal ?? null,
+                selected_action: input.selectedAction ?? null,
+                outcome: input.outcome,
+                safe_code: input.safeCode ?? null,
+                revision: 2,
+                settled_at: input.occurredAt,
+                retention_expires_at: retentionExpiresAt,
+                updated_at: input.occurredAt,
+            },
+            retention: [
+                {
+                    collection: "enforcement_claims",
+                    where: { guild_id: input.guildId, claim_key: input.claimKey },
+                    scheduledFor: retentionExpiresAt,
+                    idempotencyKey: `claim:${input.claimKey}`,
+                },
+            ],
+        });
+    }
+    async listReceipts(input) {
+        if (!Number.isInteger(input.limit) ||
+            input.limit < 1 ||
+            input.limit > AUTOMOD_LIMITS.activityPageSize)
+            throw new Error("Auto Moderation activity page size is invalid.");
+        const page = await this.#records.findMany({
+            moduleId: AUTOMOD_MODULE_ID,
+            collection: "action_receipts",
+            select: RECEIPT_FIELDS,
+            where: {
+                guild_id: input.guildId,
+                ...(input.ruleId ? { rule_id: input.ruleId } : {}),
+                ...(input.outcome ? { outcome: input.outcome } : {}),
+            },
+            orderBy: [
+                { field: "occurred_at", direction: "desc" },
+                { field: "receipt_id", direction: "desc" },
+            ],
+            ...(input.cursor ? { cursor: input.cursor } : {}),
+            limit: input.limit,
+        });
+        return { items: page.records.map(mapReceipt), nextCursor: page.nextCursor };
+    }
+    async findReceipt(guildId, receiptId) {
+        const row = await this.#records.findOne({
+            moduleId: AUTOMOD_MODULE_ID,
+            collection: "action_receipts",
+            select: RECEIPT_FIELDS,
+            where: { guild_id: guildId, receipt_id: receiptId },
+        });
+        return row ? mapReceipt(row) : null;
+    }
+}
+function audit(guildId, actorUserId, action, targetId, idempotencyKey) {
+    return {
+        guildId,
+        ...(actorUserId ? { actorUserId } : {}),
+        action,
+        source: actorUserId ? "dashboard" : "system",
+        idempotencyKey,
+        targetType: "automod_rule",
+        targetId,
+    };
+}
+function isServiceAccess(value) {
+    return "get" in value && typeof value.get === "function";
+}
+function addDays(value, days) {
+    return new Date(value.getTime() + days * 86_400_000);
+}
+//# sourceMappingURL=repository.js.map

package/dist/resource-cursor.d.ts

@@ -0,0 +1,5 @@
+import { type ModuleRecordWriteValue } from "@helyx/sdk";
+export declare function cursorBinding(guildId: string, search?: string, filters?: Readonly<Record<string, string>>): string;
+export declare function encodeCursor(values: readonly ModuleRecordWriteValue[], binding: string): string;
+export declare function decodeCursor(cursor: string | undefined, binding: string): readonly ModuleRecordWriteValue[] | undefined;
+//# sourceMappingURL=resource-cursor.d.ts.map

package/dist/resource-cursor.js

@@ -0,0 +1,45 @@
+import { DashboardActionValidationError, } from "@helyx/sdk";
+export function cursorBinding(guildId, search, filters) {
+    return JSON.stringify({
+        version: 1,
+        guildId,
+        search: search?.trim() ?? null,
+        status: filters?.status ?? null,
+        order: "updated_desc",
+    });
+}
+export function encodeCursor(values, binding) {
+    return Buffer.from(JSON.stringify({
+        version: 1,
+        binding,
+        values: values.map((value) => value instanceof Date ? { date: value.toISOString() } : value),
+    }), "utf8").toString("base64url");
+}
+export function decodeCursor(cursor, binding) {
+    if (!cursor)
+        return undefined;
+    try {
+        const parsed = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+        if (parsed.version !== 1 ||
+            parsed.binding !== binding ||
+            !Array.isArray(parsed.values))
+            throw new Error();
+        return parsed.values.map(cursorValue);
+    }
+    catch {
+        throw new DashboardActionValidationError("The Auto Moderation cursor is invalid.");
+    }
+}
+function cursorValue(value) {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        const candidate = value;
+        if (typeof candidate.date === "string")
+            return new Date(candidate.date);
+    }
+    if (typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean")
+        return value;
+    throw new Error("Invalid cursor value");
+}
+//# sourceMappingURL=resource-cursor.js.map

package/dist/resource-presentation.d.ts

@@ -0,0 +1,21 @@
+import type { ManagedResourceDetail, MessageResponse } from "@helyx/sdk";
+import type { AutoModerationRuleDraft } from "./domain.js";
+import type { StoredAutoModerationRule } from "./repository.js";
+export declare function previewMessage(draft: AutoModerationRuleDraft): MessageResponse;
+export declare function ruleSummary(rule: StoredAutoModerationRule): {
+    id: string;
+    revision: number;
+    status: import("./domain.js").AutoModerationRuleStatus;
+    title: string;
+    description: string;
+    attributes: {
+        filter: string;
+        action: string;
+        moderationThread: string;
+        ignoredRoles: readonly string[];
+        repeatOffender: string;
+    };
+    updatedAt: string;
+};
+export declare function ruleDetail(rule: StoredAutoModerationRule): ManagedResourceDetail;
+//# sourceMappingURL=resource-presentation.d.ts.map