@joliegg/moderation 0.6.0 → 0.8.0

package/dist/raid/age.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Is a member's account "too new" for the given threshold?
+ *
+ * Returns `false` when both timestamps are missing.
+ */
+export declare function isAccountTooNew(joinedTimestamp: number | null, createdTimestamp: number | null, minAgeDays: number): boolean;

package/dist/raid/age.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAccountTooNew = isAccountTooNew;
+/**
+ * Is a member's account "too new" for the given threshold?
+ *
+ * Returns `false` when both timestamps are missing.
+ */
+function isAccountTooNew(joinedTimestamp, createdTimestamp, minAgeDays) {
+    // For raids, we care about join time, not account creation
+    // Altough we can derive some trust from that too.
+    const reference = joinedTimestamp ?? createdTimestamp;
+    if (reference === null) {
+        return false;
+    }
+    const age = Date.now() - reference;
+    const minAgeMs = minAgeDays * 24 * 60 * 60 * 1000;
+    return age < minAgeMs;
+}

package/dist/raid/detector.d.ts

@@ -0,0 +1,56 @@
+export interface RaidDetectorOptions {
+    /** Number of joins within the window that constitutes a raid. Default to 10 (very small community) but this really depends on community size and activity. */
+    joinThreshold?: number;
+    /** Sliding window in seconds. Default to 60 seconds (1 minute). */
+    joinWindow?: number;
+}
+export interface MemberJoin {
+    memberId: string;
+    joinedTimestamp: number;
+    createdTimestamp: number;
+}
+export interface RaidTrackResult {
+    isRaid: boolean;
+    joinCount: number;
+    windowSeconds: number;
+}
+export type EnableResult = 'enabled' | 'already_active' | 'already_enabling';
+/**
+ * Platform-agnostic raid detector. Tracks recent joins per guild in a
+ * sliding window and surfaces the "raid" signal when the join count
+ * crosses the configured threshold.
+ *
+ * State transitions (`tryEnable`, `disable`) are guarded by an
+ * in-memory mutex so concurrent `handleMemberJoin` invocations during
+ * a join burst cannot both see "not active" and double-fire the
+ * enable side effects.
+ *
+ * The detector owns the sliding-window state. It does NOT own the
+ * enforcement — callers decide what to do when `isRaid` is true
+ * (timeout, kick, auto-disable timer, mod-channel alert, etc.).
+ */
+export declare class RaidDetector {
+    readonly joinThreshold: number;
+    readonly joinWindow: number;
+    private state;
+    private enabling;
+    constructor(options?: RaidDetectorOptions);
+    private getState;
+    private cleanupJoins;
+    /**
+     * Record a join and return whether the guild has crossed the raid
+     * threshold inside the window. `tryEnable` is a separate call so the
+     * caller can act on the raid signal atomically.
+     */
+    track(guildId: string, member: MemberJoin): RaidTrackResult;
+    isActive(guildId: string): boolean;
+    /**
+     * Attempt to flip the guild into raid-active state. Returns:
+     *  - 'enabled' if this call performed the transition
+     *  - 'already_active' if raid mode was already on
+     *  - 'already_enabling' if another concurrent call is mid-transition
+     */
+    tryEnable(guildId: string): Promise<EnableResult>;
+    disable(guildId: string): void;
+    getJoinCount(guildId: string, windowSeconds?: number): number;
+}

package/dist/raid/detector.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RaidDetector = void 0;
+/**
+ * Platform-agnostic raid detector. Tracks recent joins per guild in a
+ * sliding window and surfaces the "raid" signal when the join count
+ * crosses the configured threshold.
+ *
+ * State transitions (`tryEnable`, `disable`) are guarded by an
+ * in-memory mutex so concurrent `handleMemberJoin` invocations during
+ * a join burst cannot both see "not active" and double-fire the
+ * enable side effects.
+ *
+ * The detector owns the sliding-window state. It does NOT own the
+ * enforcement — callers decide what to do when `isRaid` is true
+ * (timeout, kick, auto-disable timer, mod-channel alert, etc.).
+ */
+class RaidDetector {
+    joinThreshold;
+    joinWindow;
+    state = new Map();
+    enabling = new Set();
+    constructor(options = {}) {
+        this.joinThreshold = options.joinThreshold ?? 10;
+        this.joinWindow = (options.joinWindow ?? 60) * 1000;
+    }
+    getState(guildId) {
+        if (!this.state.has(guildId)) {
+            this.state.set(guildId, { joins: [], raidActive: false });
+        }
+        return this.state.get(guildId);
+    }
+    cleanupJoins(state, now) {
+        state.joins = state.joins.filter(j => now - j.timestamp < this.joinWindow);
+    }
+    /**
+     * Record a join and return whether the guild has crossed the raid
+     * threshold inside the window. `tryEnable` is a separate call so the
+     * caller can act on the raid signal atomically.
+     */
+    track(guildId, member) {
+        const now = Date.now();
+        const state = this.getState(guildId);
+        this.cleanupJoins(state, now);
+        state.joins.push({ memberId: member.memberId, timestamp: now });
+        return {
+            isRaid: state.joins.length >= this.joinThreshold,
+            joinCount: state.joins.length,
+            windowSeconds: this.joinWindow / 1000,
+        };
+    }
+    isActive(guildId) {
+        return this.state.get(guildId)?.raidActive ?? false;
+    }
+    /**
+     * Attempt to flip the guild into raid-active state. Returns:
+     *  - 'enabled' if this call performed the transition
+     *  - 'already_active' if raid mode was already on
+     *  - 'already_enabling' if another concurrent call is mid-transition
+     */
+    async tryEnable(guildId) {
+        const state = this.getState(guildId);
+        if (state.raidActive)
+            return 'already_active';
+        if (this.enabling.has(guildId))
+            return 'already_enabling';
+        this.enabling.add(guildId);
+        try {
+            state.raidActive = true;
+            return 'enabled';
+        }
+        finally {
+            this.enabling.delete(guildId);
+        }
+    }
+    disable(guildId) {
+        const state = this.getState(guildId);
+        state.raidActive = false;
+        this.enabling.delete(guildId);
+    }
+    getJoinCount(guildId, windowSeconds) {
+        const now = Date.now();
+        const state = this.getState(guildId);
+        const window = (windowSeconds ?? this.joinWindow / 1000) * 1000;
+        return state.joins.filter(j => now - j.timestamp < window).length;
+    }
+}
+exports.RaidDetector = RaidDetector;

package/dist/raid/index.d.ts

@@ -0,0 +1,2 @@
+export * from './detector';
+export * from './age';

package/dist/raid/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./detector"), exports);
+__exportStar(require("./age"), exports);

package/dist/spam/cache.d.ts

@@ -0,0 +1,99 @@
+export interface SpamCacheOptions {
+    /** Maximum messages allowed within the rate-limit window. Default 8. */
+    rateLimit?: number;
+    /** Rate-limit window in seconds. Default 10. */
+    rateLimitWindow?: number;
+    /** How many identical messages trigger a duplicate alert. Default 3. */
+    duplicateThreshold?: number;
+    /** Duplicate-detection window in seconds. Default 30. */
+    duplicateWindow?: number;
+    /** Daytime timeout duration in minutes. Default 180. */
+    timeoutDurationDay?: number;
+    /** Hour of day (0-23) when nighttime timeouts start. Default 23. */
+    nightStartHour?: number;
+    /** Hour of day (0-23) when nighttime timeouts end. Default 11. */
+    nightEndHour?: number;
+    /** IANA timezone for night detection. Default 'America/Mexico_City'. */
+    timezone?: string;
+    /** LRU capacity for tracked users. Default 10000. */
+    maxUsers?: number;
+}
+export interface SpamContent {
+    text?: string;
+    attachments?: {
+        name: string;
+        size: number;
+    }[];
+    stickerIds?: string[];
+    messageId?: string | null;
+    channelId?: string | null;
+}
+export interface SpamMessageRef {
+    messageId: string;
+    channelId: string;
+}
+export type SpamReason = 'rate_limit' | 'duplicate';
+export interface SpamResult {
+    isSpam: boolean;
+    reason: SpamReason | null;
+    details: string | null;
+    /**
+     * Message references that contributed to the spam trigger.
+     */
+    priorMessageIds?: SpamMessageRef[];
+}
+export interface SpamCacheStats {
+    trackedUsers: number;
+    maxUsers: number;
+    totalTimestamps: number;
+    totalHashes: number;
+    config: {
+        rateLimit: number;
+        rateLimitWindowSeconds: number;
+        duplicateThreshold: number;
+        duplicateWindowSeconds: number;
+        timeoutDurationDayMinutes: number;
+        nightHours: string;
+        timezone: string;
+        isNightTime: boolean;
+        currentTimeoutMinutes: number;
+    };
+}
+/**
+ * Spam Cache. Tracks per-user message timestamps and content hashes to detect
+ * three kinds of abuse:
+ *
+ *  - Rate limit: too many messages in a rolling window
+ *  - Duplicate: the same content repeated across messages
+ *  - Cross-channel: the same user hopping channels in quick succession
+ *
+ * Consumers are responsible for calling `cleanup()` periodically to
+ * evict expired entries.
+ */
+export declare class SpamCache {
+    readonly rateLimit: number;
+    readonly rateLimitWindow: number;
+    readonly duplicateThreshold: number;
+    readonly duplicateWindow: number;
+    readonly timeoutDurationDay: number;
+    readonly nightStartHour: number;
+    readonly nightEndHour: number;
+    readonly timezone: string;
+    readonly maxUsers: number;
+    private userTracking;
+    constructor(options?: SpamCacheOptions);
+    private hashContent;
+    private generateContentId;
+    private getTracking;
+    private cleanupTracking;
+    track(userId: string, content: SpamContent): SpamResult;
+    reset(userId: string): void;
+    clear(): void;
+    getStats(): SpamCacheStats;
+    private getCurrentTime;
+    isNightTime(): boolean;
+    getMinutesUntilNightEnd(): number;
+    getTimeoutDurationMinutes(): number;
+    getTimeoutDurationMs(): number;
+    cleanup(): number;
+}

package/dist/spam/cache.js

@@ -0,0 +1,210 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpamCache = void 0;
+const node_crypto_1 = require("node:crypto");
+const normalize_1 = require("../text/normalize");
+/**
+ * MD5 hash for content fingerprinting.
+ *
+ * Prefers Bun.CryptoHasher when available, falls back to node:crypto
+ */
+const md5 = (input) => {
+    // @ts-expect-error — Bun global is not in node types
+    if (typeof Bun !== 'undefined' && Bun.CryptoHasher) {
+        // @ts-expect-error — same
+        const hasher = new Bun.CryptoHasher('md5');
+        hasher.update(input);
+        return hasher.digest('hex');
+    }
+    return (0, node_crypto_1.createHash)('md5').update(input).digest('hex');
+};
+/**
+ * Spam Cache. Tracks per-user message timestamps and content hashes to detect
+ * three kinds of abuse:
+ *
+ *  - Rate limit: too many messages in a rolling window
+ *  - Duplicate: the same content repeated across messages
+ *  - Cross-channel: the same user hopping channels in quick succession
+ *
+ * Consumers are responsible for calling `cleanup()` periodically to
+ * evict expired entries.
+ */
+class SpamCache {
+    rateLimit;
+    rateLimitWindow;
+    duplicateThreshold;
+    duplicateWindow;
+    timeoutDurationDay;
+    nightStartHour;
+    nightEndHour;
+    timezone;
+    maxUsers;
+    userTracking = new Map();
+    constructor(options = {}) {
+        this.rateLimit = options.rateLimit ?? 8;
+        this.rateLimitWindow = (options.rateLimitWindow ?? 10) * 1000;
+        this.duplicateThreshold = options.duplicateThreshold ?? 3;
+        this.duplicateWindow = (options.duplicateWindow ?? 30) * 1000;
+        this.timeoutDurationDay = options.timeoutDurationDay ?? 180;
+        this.nightStartHour = options.nightStartHour ?? 23;
+        this.nightEndHour = options.nightEndHour ?? 11;
+        this.timezone = options.timezone ?? 'America/Mexico_City';
+        this.maxUsers = options.maxUsers ?? 10000;
+    }
+    hashContent(content) {
+        return md5((0, normalize_1.normalizeText)(content));
+    }
+    generateContentId(options) {
+        const { text, attachments = [], stickerIds = [] } = options;
+        const parts = [];
+        if (text && text.trim()) {
+            parts.push(`text:${this.hashContent(text)}`);
+        }
+        if (attachments.length > 0) {
+            const fingerprints = attachments.map(a => `${a.name}:${a.size}`).sort();
+            parts.push(`attachments:${this.hashContent(fingerprints.join('|'))}`);
+        }
+        if (stickerIds.length > 0) {
+            const sorted = [...stickerIds].sort();
+            parts.push(`stickers:${sorted.join(',')}`);
+        }
+        if (parts.length === 0) {
+            return `empty:${Date.now()}`;
+        }
+        return parts.join('::');
+    }
+    getTracking(userId) {
+        if (!this.userTracking.has(userId)) {
+            if (this.userTracking.size >= this.maxUsers) {
+                const firstKey = this.userTracking.keys().next().value;
+                if (firstKey !== undefined) {
+                    this.userTracking.delete(firstKey);
+                }
+            }
+            this.userTracking.set(userId, { timestamps: [], messageHashes: [] });
+        }
+        return this.userTracking.get(userId);
+    }
+    cleanupTracking(tracking, now) {
+        tracking.timestamps = tracking.timestamps.filter(e => now - e.time < this.rateLimitWindow);
+        tracking.messageHashes = tracking.messageHashes.filter(e => now - e.timestamp < this.duplicateWindow);
+    }
+    track(userId, content) {
+        const now = Date.now();
+        const tracking = this.getTracking(userId);
+        this.cleanupTracking(tracking, now);
+        const messageId = content.messageId ?? null;
+        const channelId = content.channelId ?? null;
+        const contentId = this.generateContentId(content);
+        tracking.timestamps.push({ time: now, channelId, messageId });
+        const collectPriorMessageIds = () => tracking.timestamps
+            .filter(t => t.messageId && t.channelId)
+            .map(t => ({ messageId: t.messageId, channelId: t.channelId }));
+        if (tracking.timestamps.length > this.rateLimit) {
+            return {
+                isSpam: true,
+                reason: 'rate_limit',
+                details: `Sent ${tracking.timestamps.length} messages in ${this.rateLimitWindow / 1000} seconds (limit: ${this.rateLimit})`,
+                priorMessageIds: collectPriorMessageIds(),
+            };
+        }
+        const uniqueChannels = new Set(tracking.timestamps.map(t => t.channelId).filter(Boolean)).size;
+        if (uniqueChannels >= 3) {
+            return {
+                isSpam: true,
+                reason: 'rate_limit',
+                details: `Cross-channel spam detected: Posted in ${uniqueChannels} channels in ${this.rateLimitWindow / 1000} seconds`,
+                priorMessageIds: collectPriorMessageIds(),
+            };
+        }
+        if (!contentId.startsWith('empty:')) {
+            const duplicates = tracking.messageHashes.filter(e => e.hash === contentId);
+            const duplicateCount = duplicates.length;
+            tracking.messageHashes.push({ hash: contentId, timestamp: now, messageId, channelId });
+            if (duplicateCount >= this.duplicateThreshold - 1) {
+                const priorMessageIds = duplicates
+                    .filter(e => e.messageId && e.channelId)
+                    .map(e => ({ messageId: e.messageId, channelId: e.channelId }));
+                return {
+                    isSpam: true,
+                    reason: 'duplicate',
+                    details: `Sent the same content ${duplicateCount + 1} times in ${this.duplicateWindow / 1000} seconds (limit: ${this.duplicateThreshold})`,
+                    priorMessageIds,
+                };
+            }
+        }
+        else {
+            tracking.messageHashes.push({ hash: contentId, timestamp: now, messageId, channelId });
+        }
+        return { isSpam: false, reason: null, details: null };
+    }
+    reset(userId) {
+        this.userTracking.delete(userId);
+    }
+    clear() {
+        this.userTracking.clear();
+    }
+    getStats() {
+        let totalTimestamps = 0;
+        let totalHashes = 0;
+        for (const tracking of this.userTracking.values()) {
+            totalTimestamps += tracking.timestamps.length;
+            totalHashes += tracking.messageHashes.length;
+        }
+        return {
+            trackedUsers: this.userTracking.size,
+            maxUsers: this.maxUsers,
+            totalTimestamps,
+            totalHashes,
+            config: {
+                rateLimit: this.rateLimit,
+                rateLimitWindowSeconds: this.rateLimitWindow / 1000,
+                duplicateThreshold: this.duplicateThreshold,
+                duplicateWindowSeconds: this.duplicateWindow / 1000,
+                timeoutDurationDayMinutes: this.timeoutDurationDay,
+                nightHours: `${this.nightStartHour}:00 - ${this.nightEndHour}:00`,
+                timezone: this.timezone,
+                isNightTime: this.isNightTime(),
+                currentTimeoutMinutes: this.getTimeoutDurationMinutes(),
+            },
+        };
+    }
+    getCurrentTime() {
+        const now = new Date();
+        const hour = parseInt(new Intl.DateTimeFormat('en-US', { timeZone: this.timezone, hour: 'numeric', hour12: false }).format(now));
+        const minute = parseInt(new Intl.DateTimeFormat('en-US', { timeZone: this.timezone, minute: 'numeric' }).format(now));
+        return { hour, minute };
+    }
+    isNightTime() {
+        const { hour } = this.getCurrentTime();
+        if (this.nightStartHour > this.nightEndHour) {
+            return hour >= this.nightStartHour || hour < this.nightEndHour;
+        }
+        return hour >= this.nightStartHour && hour < this.nightEndHour;
+    }
+    getMinutesUntilNightEnd() {
+        const { hour, minute } = this.getCurrentTime();
+        const hoursUntilEnd = hour >= this.nightStartHour ? (24 - hour) + this.nightEndHour : this.nightEndHour - hour;
+        const totalMinutes = hoursUntilEnd * 60 - minute;
+        return Math.max(totalMinutes, 60);
+    }
+    getTimeoutDurationMinutes() {
+        return this.isNightTime() ? this.getMinutesUntilNightEnd() : this.timeoutDurationDay;
+    }
+    getTimeoutDurationMs() {
+        return this.getTimeoutDurationMinutes() * 60 * 1000;
+    }
+    cleanup() {
+        const now = Date.now();
+        const toDelete = [];
+        for (const [userId, tracking] of this.userTracking.entries()) {
+            this.cleanupTracking(tracking, now);
+            if (tracking.timestamps.length === 0 && tracking.messageHashes.length === 0) {
+                toDelete.push(userId);
+            }
+        }
+        toDelete.forEach(userId => this.userTracking.delete(userId));
+        return toDelete.length;
+    }
+}
+exports.SpamCache = SpamCache;

package/dist/spam/index.d.ts

@@ -0,0 +1 @@
+export * from './cache';

package/dist/spam/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./cache"), exports);

package/dist/text/index.d.ts

@@ -0,0 +1,2 @@
+export * from './normalize';
+export * from './mentions';

package/dist/text/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./normalize"), exports);
+__exportStar(require("./mentions"), exports);

package/dist/text/mentions.d.ts

@@ -0,0 +1,31 @@
+export interface MentionConfig {
+    /** Maximum number of distinct user mentions per message. */
+    maxUserMentions: number;
+    /** Maximum number of distinct role mentions per message. */
+    maxRoleMentions: number;
+    /** Maximum number of total mentions (user + role) per message. */
+    maxTotalMentions: number;
+    /** Whether to treat `@everyone` as spam for the sender. */
+    blockEveryone: boolean;
+    /** Whether to treat `@here` as spam for the sender. */
+    blockHere: boolean;
+}
+export interface MentionCounts {
+    userMentions: number;
+    roleMentions: number;
+    hasEveryone: boolean;
+    hasHere: boolean;
+}
+export type MentionSpamReason = 'mention_everyone' | 'mention_here' | 'mention_users' | 'mention_roles' | 'mention_total';
+export interface MentionSpamResult {
+    isSpam: boolean;
+    reason: MentionSpamReason | null;
+    details: string | null;
+}
+export declare const DEFAULT_MENTION_CONFIG: MentionConfig;
+/**
+ * Mention-spam check.
+ *
+ * `@everyone` detection takes priority over other reasons.
+ */
+export declare function checkMentionSpam(counts: MentionCounts, config: MentionConfig): MentionSpamResult;

package/dist/text/mentions.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MENTION_CONFIG = void 0;
+exports.checkMentionSpam = checkMentionSpam;
+exports.DEFAULT_MENTION_CONFIG = {
+    maxUserMentions: 5,
+    maxRoleMentions: 3,
+    maxTotalMentions: 8,
+    blockEveryone: true,
+    blockHere: true,
+};
+/**
+ * Mention-spam check.
+ *
+ * `@everyone` detection takes priority over other reasons.
+ */
+function checkMentionSpam(counts, config) {
+    if (config.blockEveryone && counts.hasEveryone) {
+        return {
+            isSpam: true,
+            reason: 'mention_everyone',
+            details: '@everyone mentioned without permission',
+        };
+    }
+    if (config.blockHere && counts.hasHere) {
+        return {
+            isSpam: true,
+            reason: 'mention_here',
+            details: '@here mentioned without permission',
+        };
+    }
+    if (counts.userMentions > config.maxUserMentions) {
+        return {
+            isSpam: true,
+            reason: 'mention_users',
+            details: `${counts.userMentions} user mentions (limit: ${config.maxUserMentions})`,
+        };
+    }
+    if (counts.roleMentions > config.maxRoleMentions) {
+        return {
+            isSpam: true,
+            reason: 'mention_roles',
+            details: `${counts.roleMentions} role mentions (limit: ${config.maxRoleMentions})`,
+        };
+    }
+    const total = counts.userMentions + counts.roleMentions;
+    if (total > config.maxTotalMentions) {
+        return {
+            isSpam: true,
+            reason: 'mention_total',
+            details: `${total} total mentions (limit: ${config.maxTotalMentions})`,
+        };
+    }
+    return { isSpam: false, reason: null, details: null };
+}

package/dist/text/normalize.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Canonicalizes user-submitted text for content matching:
+ *
+ *  1. trim surrounding whitespace
+ *  2. lowercase
+ *  3. strip zero-width / invisible characters
+ *  4. NFKC normalize (collapses bold, italic, fullwidth, circled,
+ *     small-caps, and other compatibility variants to ASCII)
+ *  5. collapse internal whitespace runs to single spaces
+ *
+ * Useful for spam hashing, ban-list matching, and any other comparison
+ * where users should not be able to defeat a match by visually similar
+ * but technically distinct input.
+ */
+export declare function normalizeText(input: string): string;