@joliegg/moderation 0.6.0 → 0.9.0

package/dist/actions.d.ts

@@ -0,0 +1,28 @@
+import type { Severity } from './types';
+/**
+ * Moderation actions taxonomy. These should be stable so they can be persisted
+ * as a canonical list of actions.
+ */
+export declare const ACTION_TYPES: {
+    readonly TIMEOUT: "timeout";
+    readonly BAN: "ban";
+    readonly KICK: "kick";
+    readonly WARN: "warn";
+    readonly DELETE: "delete";
+    readonly RESTRICT: "restrict";
+    readonly APPEAL_APPROVE: "appeal_approve";
+    readonly APPEAL_DENY: "appeal_deny";
+    readonly MENTION_SPAM: "mention_spam";
+    readonly NEW_USER_RESTRICT: "new_user_restrict";
+    readonly SPAM_DETECTED: "spam_detected";
+    readonly ESCALATION: "escalation";
+    readonly RAID_DETECTED: "raid_detected";
+    readonly RAID_TIMEOUT: "raid_timeout";
+    readonly RAID_JOIN: "raid_join";
+    readonly PERMISSION_BLOCK: "permission_block";
+    readonly UNTIMEOUT: "untimeout";
+    readonly UNBAN: "unban";
+};
+export type ActionType = typeof ACTION_TYPES[keyof typeof ACTION_TYPES];
+/** Default severity per action type. */
+export declare const SEVERITY_BY_ACTION: Record<ActionType, Severity>;

package/dist/actions.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SEVERITY_BY_ACTION = exports.ACTION_TYPES = void 0;
+/**
+ * Moderation actions taxonomy. These should be stable so they can be persisted
+ * as a canonical list of actions.
+ */
+exports.ACTION_TYPES = {
+    TIMEOUT: 'timeout',
+    BAN: 'ban',
+    KICK: 'kick',
+    WARN: 'warn',
+    DELETE: 'delete',
+    RESTRICT: 'restrict',
+    APPEAL_APPROVE: 'appeal_approve',
+    APPEAL_DENY: 'appeal_deny',
+    MENTION_SPAM: 'mention_spam',
+    NEW_USER_RESTRICT: 'new_user_restrict',
+    SPAM_DETECTED: 'spam_detected',
+    ESCALATION: 'escalation',
+    RAID_DETECTED: 'raid_detected',
+    RAID_TIMEOUT: 'raid_timeout',
+    RAID_JOIN: 'raid_join',
+    PERMISSION_BLOCK: 'permission_block',
+    UNTIMEOUT: 'untimeout',
+    UNBAN: 'unban',
+};
+/** Default severity per action type. */
+exports.SEVERITY_BY_ACTION = {
+    timeout: 'medium',
+    ban: 'critical',
+    kick: 'high',
+    warn: 'low',
+    delete: 'low',
+    restrict: 'medium',
+    appeal_approve: 'low',
+    appeal_deny: 'low',
+    mention_spam: 'medium',
+    new_user_restrict: 'low',
+    spam_detected: 'medium',
+    escalation: 'high',
+    raid_detected: 'critical',
+    raid_timeout: 'medium',
+    raid_join: 'low',
+    permission_block: 'low',
+    untimeout: 'low',
+    unban: 'low',
+};

package/dist/audit/emitter.d.ts

@@ -0,0 +1,26 @@
+import type { AuditEvent, AuditEventKind, AuditEventMap } from './events';
+/**
+ * Subscriber handler type for a specific audit event kind. Sync or
+ * async; the emitter fire-and-forgets async handlers so slow
+ * persistence sinks don't block the enforcement path.
+ */
+export type AuditHandler<K extends AuditEventKind> = (event: AuditEventMap[K]) => void | Promise<void>;
+/**
+ * Typed event emitter for moderation audit events.
+ *
+ * Subscribers register for specific event kinds with full type safety.
+ * Handlers that throw are isolated — a broken subscriber never blocks
+ * other subscribers or the emitter itself.
+ *
+ * Intentionally NOT `extends EventEmitter` from `node:events`: the
+ * typing story for Node's built-in emitter is painful, and the feature
+ * set we need (on / off / emit) is small enough to implement directly.
+ */
+export declare class AuditTrailEmitter {
+    private handlers;
+    on<K extends AuditEventKind>(kind: K, handler: AuditHandler<K>): this;
+    off<K extends AuditEventKind>(kind: K, handler: AuditHandler<K>): this;
+    emit(event: AuditEvent): void;
+    listenerCount(kind: AuditEventKind): number;
+    removeAllListeners(kind?: AuditEventKind): this;
+}

package/dist/audit/emitter.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuditTrailEmitter = void 0;
+/**
+ * Typed event emitter for moderation audit events.
+ *
+ * Subscribers register for specific event kinds with full type safety.
+ * Handlers that throw are isolated — a broken subscriber never blocks
+ * other subscribers or the emitter itself.
+ *
+ * Intentionally NOT `extends EventEmitter` from `node:events`: the
+ * typing story for Node's built-in emitter is painful, and the feature
+ * set we need (on / off / emit) is small enough to implement directly.
+ */
+class AuditTrailEmitter {
+    handlers = new Map();
+    on(kind, handler) {
+        if (!this.handlers.has(kind)) {
+            this.handlers.set(kind, new Set());
+        }
+        this.handlers.get(kind).add(handler);
+        return this;
+    }
+    off(kind, handler) {
+        this.handlers.get(kind)?.delete(handler);
+        return this;
+    }
+    emit(event) {
+        const handlers = this.handlers.get(event.kind);
+        if (!handlers) {
+            return;
+        }
+        for (const handler of handlers) {
+            try {
+                // Fire-and-forget. Async handlers are not awaited so the
+                // emitter's caller isn't blocked on slow persistence sinks.
+                // Subscribers own their own error handling for async work.
+                const result = handler(event);
+                if (result instanceof Promise) {
+                    result.catch(err => {
+                        console.error(`[Jolie::Moderation::AuditTrail] async handler error for ${event.kind}:`, err);
+                    });
+                }
+            }
+            catch (err) {
+                console.error(`[Jolie::Moderation::AuditTrail] handler error for ${event.kind}:`, err);
+            }
+        }
+    }
+    listenerCount(kind) {
+        return this.handlers.get(kind)?.size ?? 0;
+    }
+    removeAllListeners(kind) {
+        if (kind) {
+            this.handlers.delete(kind);
+        }
+        else {
+            this.handlers.clear();
+        }
+        return this;
+    }
+}
+exports.AuditTrailEmitter = AuditTrailEmitter;

package/dist/audit/events.d.ts

@@ -0,0 +1,75 @@
+import type { ActionType } from '../actions';
+import type { SpamMessageRef, SpamReason } from '../spam/cache';
+export type Platform = 'discord' | 'twitch';
+/** Base fields shared by every audit event. */
+interface AuditEventBase {
+    guildId: string;
+    platform: Platform;
+    timestamp: Date;
+}
+/**
+ * A moderator (human or system) performed an enforcement action.
+ * This is the primary audit log entry.
+ */
+export interface ActionEvent extends AuditEventBase {
+    kind: 'action';
+    actionType: ActionType;
+    targetId: string;
+    targetName: string;
+    moderatorId: string;
+    moderatorName: string;
+    reason: string;
+    details?: string;
+    duration?: number;
+    channelId?: string;
+    messageId?: string;
+    evidence?: string[];
+}
+/**
+ * Automatic spam detection fired. Independent of whether enforcement
+ * succeeded — the detection itself is the audit event.
+ */
+export interface SpamDetectedEvent extends AuditEventBase {
+    kind: 'spam_detected';
+    userId: string;
+    reason: SpamReason;
+    details?: string;
+    priorMessageIds: SpamMessageRef[];
+    channelId?: string;
+}
+/** Raid mode detection crossed the join-count threshold. */
+export interface RaidDetectedEvent extends AuditEventBase {
+    kind: 'raid_detected';
+    joinCount: number;
+    windowSeconds: number;
+    autoTriggered: boolean;
+}
+/** A message was blocked by the per-user permissions check. */
+export interface PermissionBlockEvent extends AuditEventBase {
+    kind: 'permission_block';
+    userId: string;
+    violations: string[];
+    channelId?: string;
+    messageId?: string;
+}
+/** An appeal was reviewed (approved or denied). */
+export interface AppealReviewedEvent extends AuditEventBase {
+    kind: 'appeal_reviewed';
+    appealId: string;
+    userId: string;
+    reviewerId: string;
+    approved: boolean;
+    note?: string;
+}
+/** Union of every audit event shape. Add new kinds here. */
+export type AuditEvent = ActionEvent | SpamDetectedEvent | RaidDetectedEvent | PermissionBlockEvent | AppealReviewedEvent;
+/** Map from event kind → concrete event type. Used by the emitter. */
+export interface AuditEventMap {
+    action: ActionEvent;
+    spam_detected: SpamDetectedEvent;
+    raid_detected: RaidDetectedEvent;
+    permission_block: PermissionBlockEvent;
+    appeal_reviewed: AppealReviewedEvent;
+}
+export type AuditEventKind = keyof AuditEventMap;
+export {};

package/dist/audit/events.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/audit/index.d.ts

@@ -0,0 +1,2 @@
+export * from './events';
+export * from './emitter';

package/dist/audit/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("./events"), exports);
+__exportStar(require("./emitter"), exports);

package/dist/client.d.ts

@@ -0,0 +1,22 @@
+import type { ModerationConfiguration, ModerationResult } from './types';
+/**
+ * Composes text / image / link / audio moderation across the configured
+ * providers.
+ */
+export declare class ModerationClient {
+    private googleLanguage?;
+    private googleSpeech?;
+    private aws?;
+    private webRisk?;
+    private openai?;
+    private banList;
+    private urlBlackList;
+    constructor(configuration: ModerationConfiguration);
+    moderateText(text: string, minimumConfidence?: number, options?: {
+        provider?: 'google' | 'openai' | 'all';
+    }): Promise<ModerationResult>;
+    moderateImage(url: string, minimumConfidence?: number): Promise<ModerationResult>;
+    moderateLink(url: string, allowShorteners?: boolean): Promise<ModerationResult>;
+    moderateAudio(url: string, language?: string, minimumConfidence?: number): Promise<ModerationResult>;
+}
+export default ModerationClient;

package/dist/client.js

@@ -0,0 +1,107 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ModerationClient = void 0;
+const client_rekognition_1 = require("@aws-sdk/client-rekognition");
+const language_1 = require("@google-cloud/language");
+const speech_1 = require("@google-cloud/speech");
+const google_1 = require("./providers/google");
+const aws_1 = require("./providers/aws");
+const webrisk_1 = require("./providers/webrisk");
+const openai_1 = require("./providers/openai");
+const url_blacklist_json_1 = __importDefault(require("./data/url-blacklist.json"));
+const url_shorteners_json_1 = __importDefault(require("./data/url-shorteners.json"));
+/**
+ * Composes text / image / link / audio moderation across the configured
+ * providers.
+ */
+class ModerationClient {
+    googleLanguage;
+    googleSpeech;
+    aws;
+    webRisk;
+    openai;
+    banList = [];
+    urlBlackList = [];
+    constructor(configuration) {
+        if (configuration.aws) {
+            this.aws = new aws_1.RekognitionProvider(new client_rekognition_1.Rekognition(configuration.aws));
+        }
+        if (typeof configuration.google?.keyFile === 'string') {
+            this.googleLanguage = new google_1.GoogleLanguageProvider(new language_1.LanguageServiceClient({ keyFile: configuration.google.keyFile }));
+            this.googleSpeech = new google_1.GoogleSpeechProvider(new speech_1.SpeechClient({ keyFile: configuration.google.keyFile }));
+        }
+        if (typeof configuration.google?.apiKey === 'string') {
+            this.webRisk = new webrisk_1.WebRiskProvider(configuration.google.apiKey);
+        }
+        if (typeof configuration.openai?.apiKey === 'string') {
+            this.openai = new openai_1.OpenAIModerationProvider(configuration.openai.apiKey);
+        }
+        if (Array.isArray(configuration.banList)) {
+            this.banList = configuration.banList;
+        }
+        if (Array.isArray(configuration.urlBlackList)) {
+            this.urlBlackList = configuration.urlBlackList;
+        }
+    }
+    async moderateText(text, minimumConfidence = 50, options = {}) {
+        const categories = [];
+        const normalized = text.toLowerCase();
+        const matches = this.banList.filter(w => normalized.includes(w));
+        if (matches.length > 0) {
+            const words = normalized.split(' ');
+            categories.push({ category: 'BAN_LIST', confidence: (matches.length / words.length) * 100 });
+        }
+        const provider = options.provider ?? 'google';
+        if ((provider === 'google' || provider === 'all') && this.googleLanguage) {
+            const google = await this.googleLanguage.moderateText(text, minimumConfidence);
+            categories.push(...google);
+        }
+        if ((provider === 'openai' || provider === 'all') && this.openai) {
+            const openai = await this.openai.moderateText(text, minimumConfidence);
+            categories.push(...openai);
+        }
+        return { source: text, moderation: categories };
+    }
+    async moderateImage(url, minimumConfidence = 50) {
+        if (!this.aws) {
+            return { source: url, moderation: [] };
+        }
+        const moderation = await this.aws.moderateImage(url, minimumConfidence);
+        return { source: url, moderation };
+    }
+    async moderateLink(url, allowShorteners = false) {
+        try {
+            const domain = new URL(url).hostname;
+            if (this.urlBlackList.some(u => url.includes(u))) {
+                return { source: url, moderation: [{ category: 'CUSTOM_BLACK_LIST', confidence: 100 }] };
+            }
+            if (url_blacklist_json_1.default.some(u => u === domain)) {
+                return { source: url, moderation: [{ category: 'BLACK_LIST', confidence: 100 }] };
+            }
+            if (!allowShorteners && url_shorteners_json_1.default.some(u => u === domain)) {
+                return { source: url, moderation: [{ category: 'URL_SHORTENER', confidence: 100 }] };
+            }
+        }
+        catch {
+            return { source: url, moderation: [] };
+        }
+        if (!this.webRisk) {
+            return { source: url, moderation: [] };
+        }
+        const moderation = await this.webRisk.checkLink(url);
+        return { source: url, moderation };
+    }
+    async moderateAudio(url, language = 'en-US', minimumConfidence = 50) {
+        if (!this.googleSpeech) {
+            return { source: url, moderation: [] };
+        }
+        const buffer = await (0, google_1.fetchAudio)(url);
+        const transcription = await this.googleSpeech.transcribe(buffer, language);
+        return this.moderateText(transcription, minimumConfidence);
+    }
+}
+exports.ModerationClient = ModerationClient;
+exports.default = ModerationClient;

package/dist/index.d.ts

@@ -1,41 +1,3 @@
-import { ModerationConfiguration, ModerationResult } from './types';
-/**
- * Moderation Client
- *
- * @class ModerationClient
- */
-declare class ModerationClient {
-    private rekognitionClient?;
-    private googleLanguageClient?;
-    private googleSpeechClient?;
-    private googleAPIKey?;
-    private banList?;
-    private urlBlackList?;
-    /**
-     *
-     * @param {ModerationConfiguration} configuration
-     */
-    constructor(configuration: ModerationConfiguration);
-    /**
-     * Returns a list of moderation categories detected on a text
-     *
-     * @param {string} text  The text to moderate
-     * @param {number} [minimumConfidence = 50] The minimum confidence required for a category to be considered
-     *
-     * @returns {Promise<ModerationResult>} The list of results that were detected with the minimum confidence specified
-     */
-    moderateText(text: string, minimumConfidence?: number): Promise<ModerationResult>;
-    /**
-     * Returns a list of moderation categories detected on an image
-     *
-     * @param {string} url
-     * @param {number} [minimumConfidence = 50]  The minimum confidence required for a category to be considered
-     *
-     *
-     * @returns {Promise<ModerationResult[]>} The list of results that were detected with the minimum confidence specified
-     */
-    moderateImage(url: string, minimumConfidence?: number): Promise<ModerationResult>;
-    moderateLink(url: string, allowShorteners?: boolean): Promise<ModerationResult>;
-    moderateAudio(url: string, language?: string, minimumConfidence?: number): Promise<ModerationResult>;
-}
-export default ModerationClient;
+export { ModerationClient, default } from './client';
+export * from './types';
+export * from './actions';