@joliegg/moderation 0.8.0 → 0.9.0

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

@@ -8,10 +8,13 @@ export declare class ModerationClient {
     private googleSpeech?;
     private aws?;
     private webRisk?;
+    private openai?;
     private banList;
     private urlBlackList;
     constructor(configuration: ModerationConfiguration);
-    moderateText(text: string, minimumConfidence?: number): Promise<ModerationResult>;
+    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>;

package/dist/client.js

@@ -10,6 +10,7 @@ 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"));
 /**
@@ -21,6 +22,7 @@ class ModerationClient {
     googleSpeech;
     aws;
     webRisk;
+    openai;
     banList = [];
     urlBlackList = [];
     constructor(configuration) {
@@ -34,6 +36,9 @@ class ModerationClient {
         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;
         }
@@ -41,7 +46,7 @@ class ModerationClient {
             this.urlBlackList = configuration.urlBlackList;
         }
     }
-    async moderateText(text, minimumConfidence = 50) {
+    async moderateText(text, minimumConfidence = 50, options = {}) {
         const categories = [];
         const normalized = text.toLowerCase();
         const matches = this.banList.filter(w => normalized.includes(w));
@@ -49,11 +54,16 @@ class ModerationClient {
             const words = normalized.split(' ');
             categories.push({ category: 'BAN_LIST', confidence: (matches.length / words.length) * 100 });
         }
-        if (!this.googleLanguage) {
-            return { source: text, moderation: categories };
+        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);
         }
-        const googleCategories = await this.googleLanguage.moderateText(text, minimumConfidence);
-        return { source: text, moderation: [...categories, ...googleCategories] };
+        return { source: text, moderation: categories };
     }
     async moderateImage(url, minimumConfidence = 50) {
         if (!this.aws) {

package/dist/providers/openai.d.ts

@@ -0,0 +1,15 @@
+import type { ModerationCategory } from '../types';
+/**
+ * OpenAI Moderation API adapter.
+ *
+ * Uses the free `omni-moderation-latest` endpoint (no token cost,
+ * no SDK). Returns `ModerationCategory[]` in the same shape the
+ * Google and AWS providers return, so downstream callers can treat
+ * every provider uniformly.
+ */
+export declare class OpenAIModerationProvider {
+    private apiKey;
+    private model;
+    constructor(apiKey: string, model?: string);
+    moderateText(text: string, minimumConfidence?: number): Promise<ModerationCategory[]>;
+}

package/dist/providers/openai.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenAIModerationProvider = void 0;
+/**
+ * OpenAI Moderation API adapter.
+ *
+ * Uses the free `omni-moderation-latest` endpoint (no token cost,
+ * no SDK). Returns `ModerationCategory[]` in the same shape the
+ * Google and AWS providers return, so downstream callers can treat
+ * every provider uniformly.
+ */
+class OpenAIModerationProvider {
+    apiKey;
+    model;
+    constructor(apiKey, model = 'omni-moderation-latest') {
+        this.apiKey = apiKey;
+        this.model = model;
+    }
+    async moderateText(text, minimumConfidence = 0) {
+        if (!this.apiKey) {
+            return [];
+        }
+        let response;
+        try {
+            response = await fetch('https://api.openai.com/v1/moderations', {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${this.apiKey}`,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({ model: this.model, input: text }),
+            });
+        }
+        catch {
+            return [];
+        }
+        if (!response.ok) {
+            return [];
+        }
+        const data = (await response.json());
+        const result = data.results?.[0];
+        if (!result) {
+            return [];
+        }
+        return Object.entries(result.categories)
+            .filter(([, flagged]) => flagged)
+            .map(([category]) => ({
+            category,
+            confidence: (result.category_scores[category] ?? 0) * 100,
+        }))
+            .filter(c => c.confidence >= minimumConfidence);
+    }
+}
+exports.OpenAIModerationProvider = OpenAIModerationProvider;

package/dist/raid/detector.js

@@ -60,10 +60,12 @@ class RaidDetector {
      */
     async tryEnable(guildId) {
         const state = this.getState(guildId);
-        if (state.raidActive)
+        if (state.raidActive) {
             return 'already_active';
-        if (this.enabling.has(guildId))
+        }
+        if (this.enabling.has(guildId)) {
             return 'already_enabling';
+        }
         this.enabling.add(guildId);
         try {
             state.raidActive = true;

package/dist/rubrics/defaults.d.ts

@@ -0,0 +1,19 @@
+import { ScoringRubric } from './rubric';
+/**
+ * Aggressive defaults. Flag anything moderately suspicious, delete at
+ * 75%, timeout above 90%. Good for tight-knit communities with low
+ * tolerance for borderline content.
+ */
+export declare const STRICT_RUBRIC: ScoringRubric;
+/**
+ * Conservative defaults. Only act on very high confidence. Good for
+ * large communities where false positives are worse than false
+ * negatives.
+ */
+export declare const PERMISSIVE_RUBRIC: ScoringRubric;
+/**
+ * NSFW-only rubric. Ignores harassment, hate, violence — only acts on
+ * sexual content. Useful when text moderation is handled out-of-band
+ * but image / link moderation still needs safety filtering.
+ */
+export declare const NSFW_ONLY_RUBRIC: ScoringRubric;

package/dist/rubrics/defaults.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NSFW_ONLY_RUBRIC = exports.PERMISSIVE_RUBRIC = exports.STRICT_RUBRIC = void 0;
+const actions_1 = require("../actions");
+const rubric_1 = require("./rubric");
+/**
+ * Aggressive defaults. Flag anything moderately suspicious, delete at
+ * 75%, timeout above 90%. Good for tight-knit communities with low
+ * tolerance for borderline content.
+ */
+exports.STRICT_RUBRIC = new rubric_1.ScoringRubric([
+    { match: { minConfidence: 50 }, action: actions_1.ACTION_TYPES.WARN, severity: 'low' },
+    { match: { minConfidence: 75 }, action: actions_1.ACTION_TYPES.DELETE, severity: 'medium' },
+    { match: { minConfidence: 90 }, action: actions_1.ACTION_TYPES.TIMEOUT, severity: 'high' },
+]);
+/**
+ * Conservative defaults. Only act on very high confidence. Good for
+ * large communities where false positives are worse than false
+ * negatives.
+ */
+exports.PERMISSIVE_RUBRIC = new rubric_1.ScoringRubric([
+    { match: { minConfidence: 95 }, action: actions_1.ACTION_TYPES.DELETE, severity: 'high' },
+    { match: { minConfidence: 99 }, action: actions_1.ACTION_TYPES.TIMEOUT, severity: 'critical' },
+]);
+/**
+ * NSFW-only rubric. Ignores harassment, hate, violence — only acts on
+ * sexual content. Useful when text moderation is handled out-of-band
+ * but image / link moderation still needs safety filtering.
+ */
+exports.NSFW_ONLY_RUBRIC = new rubric_1.ScoringRubric([
+    { match: { category: 'sexual', minConfidence: 70 }, action: actions_1.ACTION_TYPES.DELETE, severity: 'high' },
+]);

package/dist/rubrics/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './rubric';
+export * from './defaults';

package/dist/rubrics/index.js

@@ -0,0 +1,19 @@
+"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("./types"), exports);
+__exportStar(require("./rubric"), exports);
+__exportStar(require("./defaults"), exports);

package/dist/rubrics/rubric.d.ts

@@ -0,0 +1,21 @@
+import type { ModerationCategory } from '../types';
+import type { RubricResult, RubricRule } from './types';
+/**
+ * Composable classifier-to-action mapping.
+ *
+ * Callers hand a `ScoringRubric` their classifier output
+ * (`ModerationCategory[]`) and get back a decision: the recommended
+ * action, the aggregate severity, and the categories that contributed.
+ *
+ * Apps can use the ship-with defaults (`STRICT_RUBRIC`,
+ * `PERMISSIVE_RUBRIC`, `NSFW_ONLY_RUBRIC`) or pass custom rules.
+ *
+ * Rules are evaluated in input order; the highest-severity match wins
+ * the recommended action. Every matched category is returned in the
+ * result so callers can explain the decision.
+ */
+export declare class ScoringRubric {
+    private rules;
+    constructor(rules: RubricRule[]);
+    evaluate(categories: ModerationCategory[]): RubricResult;
+}

package/dist/rubrics/rubric.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScoringRubric = void 0;
+const SEVERITY_ORDER = {
+    low: 0,
+    medium: 1,
+    high: 2,
+    critical: 3,
+};
+/**
+ * Composable classifier-to-action mapping.
+ *
+ * Callers hand a `ScoringRubric` their classifier output
+ * (`ModerationCategory[]`) and get back a decision: the recommended
+ * action, the aggregate severity, and the categories that contributed.
+ *
+ * Apps can use the ship-with defaults (`STRICT_RUBRIC`,
+ * `PERMISSIVE_RUBRIC`, `NSFW_ONLY_RUBRIC`) or pass custom rules.
+ *
+ * Rules are evaluated in input order; the highest-severity match wins
+ * the recommended action. Every matched category is returned in the
+ * result so callers can explain the decision.
+ */
+class ScoringRubric {
+    rules;
+    constructor(rules) {
+        this.rules = rules;
+    }
+    evaluate(categories) {
+        const matched = [];
+        const reasons = [];
+        let best = null;
+        for (const category of categories) {
+            for (const rule of this.rules) {
+                const categoryMatches = rule.match.category === undefined || category.category.includes(rule.match.category);
+                if (!categoryMatches) {
+                    continue;
+                }
+                if (category.confidence < rule.match.minConfidence) {
+                    continue;
+                }
+                matched.push(category);
+                reasons.push(`${category.category} (${category.confidence.toFixed(0)}%) >= ${rule.match.minConfidence}% → ${rule.action}`);
+                if (!best || SEVERITY_ORDER[rule.severity] > SEVERITY_ORDER[best.severity]) {
+                    best = rule;
+                }
+            }
+        }
+        return {
+            action: best?.action ?? null,
+            severity: best?.severity ?? 'low',
+            matched,
+            reasons,
+        };
+    }
+}
+exports.ScoringRubric = ScoringRubric;

package/dist/rubrics/types.d.ts

@@ -0,0 +1,27 @@
+import type { ModerationCategory, Severity } from '../types';
+import type { ActionType } from '../actions';
+export interface RubricMatch {
+    /**
+     * Category name to match. Omit for a wildcard that fires on any category.
+     * Matched with substring `includes`, so a rule for `sexual` also fires
+     * on compound categories like `sexual/minors`.
+     */
+    category?: string;
+    /** Minimum confidence (0-100) required for this rule to fire. */
+    minConfidence: number;
+}
+export interface RubricRule {
+    match: RubricMatch;
+    action: ActionType;
+    severity: Severity;
+}
+export interface RubricResult {
+    /** The action the highest-severity matched rule recommends. */
+    action: ActionType | null;
+    /** Aggregate severity — matches the winning rule, or `'low'` if nothing matched. */
+    severity: Severity;
+    /** Every category that matched at least one rule. */
+    matched: ModerationCategory[];
+    /** Human-readable explanations — one per matched rule. */
+    reasons: string[];
+}

package/dist/rubrics/types.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joliegg/moderation",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "A set of tools for chat moderation",
   "author": "Diana Islas Ocampo",
   "main": "dist/index.js",
@@ -31,6 +31,14 @@
       "types": "./dist/raid/index.d.ts",
       "default": "./dist/raid/index.js"
     },
+    "./rubrics": {
+      "types": "./dist/rubrics/index.d.ts",
+      "default": "./dist/rubrics/index.js"
+    },
+    "./audit": {
+      "types": "./dist/audit/index.d.ts",
+      "default": "./dist/audit/index.js"
+    },
     "./providers/google": {
       "types": "./dist/providers/google.d.ts",
       "default": "./dist/providers/google.js"
@@ -43,6 +51,10 @@
       "types": "./dist/providers/webrisk.d.ts",
       "default": "./dist/providers/webrisk.js"
     },
+    "./providers/openai": {
+      "types": "./dist/providers/openai.d.ts",
+      "default": "./dist/providers/openai.js"
+    },
     "./package.json": "./package.json"
   },
   "scripts": {

package/src/audit/emitter.ts

@@ -0,0 +1,77 @@
+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 class AuditTrailEmitter {
+  private handlers = new Map<AuditEventKind, Set<AuditHandler<AuditEventKind>>>();
+
+  on<K extends AuditEventKind>(kind: K, handler: AuditHandler<K>): this {
+    if (!this.handlers.has(kind)) {
+      this.handlers.set(kind, new Set());
+    }
+
+    this.handlers.get(kind)!.add(handler as AuditHandler<AuditEventKind>);
+
+    return this;
+  }
+
+  off<K extends AuditEventKind>(kind: K, handler: AuditHandler<K>): this {
+    this.handlers.get(kind)?.delete(handler as AuditHandler<AuditEventKind>);
+    return this;
+  }
+
+  emit(event: AuditEvent): void {
+    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: AuditEventKind): number {
+    return this.handlers.get(kind)?.size ?? 0;
+  }
+
+  removeAllListeners(kind?: AuditEventKind): this {
+    if (kind) {
+      this.handlers.delete(kind);
+    } else {
+      this.handlers.clear();
+    }
+
+    return this;
+  }
+}

package/src/audit/events.ts

@@ -0,0 +1,89 @@
+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;

package/src/audit/index.ts

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

package/src/client.ts

@@ -5,6 +5,7 @@ import { SpeechClient } from '@google-cloud/speech';
 import { GoogleLanguageProvider, GoogleSpeechProvider, fetchAudio } from './providers/google';
 import { RekognitionProvider } from './providers/aws';
 import { WebRiskProvider } from './providers/webrisk';
+import { OpenAIModerationProvider } from './providers/openai';
 import URLBlackList from './data/url-blacklist.json';
 import URLShortenerList from './data/url-shorteners.json';
 
@@ -19,6 +20,7 @@ export class ModerationClient {
   private googleSpeech?: GoogleSpeechProvider;
   private aws?: RekognitionProvider;
   private webRisk?: WebRiskProvider;
+  private openai?: OpenAIModerationProvider;
   private banList: string[] = [];
   private urlBlackList: string[] = [];
 
@@ -41,6 +43,10 @@ export class ModerationClient {
       this.webRisk = new WebRiskProvider(configuration.google.apiKey);
     }
 
+    if (typeof configuration.openai?.apiKey === 'string') {
+      this.openai = new OpenAIModerationProvider(configuration.openai.apiKey);
+    }
+
     if (Array.isArray(configuration.banList)) {
       this.banList = configuration.banList;
     }
@@ -50,7 +56,11 @@ export class ModerationClient {
     }
   }
 
-  async moderateText(text: string, minimumConfidence: number = 50): Promise<ModerationResult> {
+  async moderateText(
+    text: string,
+    minimumConfidence: number = 50,
+    options: { provider?: 'google' | 'openai' | 'all' } = {},
+  ): Promise<ModerationResult> {
     const categories: ModerationCategory[] = [];
     const normalized = text.toLowerCase();
     const matches = this.banList.filter(w => normalized.includes(w));
@@ -60,13 +70,19 @@ export class ModerationClient {
       categories.push({ category: 'BAN_LIST', confidence: (matches.length / words.length) * 100 });
     }
 
-    if (!this.googleLanguage) {
-      return { source: text, moderation: categories };
+    const provider = options.provider ?? 'google';
+
+    if ((provider === 'google' || provider === 'all') && this.googleLanguage) {
+      const google = await this.googleLanguage.moderateText(text, minimumConfidence);
+      categories.push(...google);
     }
 
-    const googleCategories = await this.googleLanguage.moderateText(text, minimumConfidence);
+    if ((provider === 'openai' || provider === 'all') && this.openai) {
+      const openai = await this.openai.moderateText(text, minimumConfidence);
+      categories.push(...openai);
+    }
 
-    return { source: text, moderation: [...categories, ...googleCategories] };
+    return { source: text, moderation: categories };
   }
 
   async moderateImage(url: string, minimumConfidence: number = 50): Promise<ModerationResult> {

package/src/providers/openai.ts

@@ -0,0 +1,64 @@
+import type { ModerationCategory } from '../types';
+
+interface OpenAIModerationResponse {
+  results?: Array<{
+    flagged: boolean;
+    categories: Record<string, boolean>;
+    category_scores: Record<string, number>;
+  }>;
+}
+
+/**
+ * OpenAI Moderation API adapter.
+ *
+ * Uses the free `omni-moderation-latest` endpoint (no token cost,
+ * no SDK). Returns `ModerationCategory[]` in the same shape the
+ * Google and AWS providers return, so downstream callers can treat
+ * every provider uniformly.
+ */
+export class OpenAIModerationProvider {
+  constructor(
+    private apiKey: string,
+    private model: string = 'omni-moderation-latest',
+  ) {}
+
+  async moderateText(text: string, minimumConfidence: number = 0): Promise<ModerationCategory[]> {
+    if (!this.apiKey) {
+      return [];
+    }
+
+    let response: Response;
+
+    try {
+      response = await fetch('https://api.openai.com/v1/moderations', {
+        method: 'POST',
+        headers: {
+          'Authorization': `Bearer ${this.apiKey}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ model: this.model, input: text }),
+      });
+    } catch {
+      return [];
+    }
+
+    if (!response.ok) {
+      return [];
+    }
+
+    const data = (await response.json()) as OpenAIModerationResponse;
+    const result = data.results?.[0];
+
+    if (!result) {
+      return [];
+    }
+
+    return Object.entries(result.categories)
+      .filter(([, flagged]) => flagged)
+      .map(([category]) => ({
+        category,
+        confidence: (result.category_scores[category] ?? 0) * 100,
+      }))
+      .filter(c => c.confidence >= minimumConfidence);
+  }
+}

package/src/raid/detector.ts

@@ -59,6 +59,7 @@ export class RaidDetector {
     if (!this.state.has(guildId)) {
       this.state.set(guildId, { joins: [], raidActive: false });
     }
+
     return this.state.get(guildId)!;
   }
 
@@ -74,8 +75,10 @@ export class RaidDetector {
   track(guildId: string, member: MemberJoin): RaidTrackResult {
     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,
@@ -95,9 +98,17 @@ export class RaidDetector {
    */
   async tryEnable(guildId: string): Promise<EnableResult> {
     const state = this.getState(guildId);
-    if (state.raidActive) return 'already_active';
-    if (this.enabling.has(guildId)) return 'already_enabling';
+
+    if (state.raidActive) {
+      return 'already_active';
+    }
+
+    if (this.enabling.has(guildId)) {
+      return 'already_enabling';
+    }
+
     this.enabling.add(guildId);
+
     try {
       state.raidActive = true;
       return 'enabled';

package/src/rubrics/defaults.ts

@@ -0,0 +1,32 @@
+import { ACTION_TYPES } from '../actions';
+import { ScoringRubric } from './rubric';
+
+/**
+ * Aggressive defaults. Flag anything moderately suspicious, delete at
+ * 75%, timeout above 90%. Good for tight-knit communities with low
+ * tolerance for borderline content.
+ */
+export const STRICT_RUBRIC = new ScoringRubric([
+  { match: { minConfidence: 50 }, action: ACTION_TYPES.WARN, severity: 'low' },
+  { match: { minConfidence: 75 }, action: ACTION_TYPES.DELETE, severity: 'medium' },
+  { match: { minConfidence: 90 }, action: ACTION_TYPES.TIMEOUT, severity: 'high' },
+]);
+
+/**
+ * Conservative defaults. Only act on very high confidence. Good for
+ * large communities where false positives are worse than false
+ * negatives.
+ */
+export const PERMISSIVE_RUBRIC = new ScoringRubric([
+  { match: { minConfidence: 95 }, action: ACTION_TYPES.DELETE, severity: 'high' },
+  { match: { minConfidence: 99 }, action: ACTION_TYPES.TIMEOUT, severity: 'critical' },
+]);
+
+/**
+ * NSFW-only rubric. Ignores harassment, hate, violence — only acts on
+ * sexual content. Useful when text moderation is handled out-of-band
+ * but image / link moderation still needs safety filtering.
+ */
+export const NSFW_ONLY_RUBRIC = new ScoringRubric([
+  { match: { category: 'sexual', minConfidence: 70 }, action: ACTION_TYPES.DELETE, severity: 'high' },
+]);

package/src/rubrics/index.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './rubric';
+export * from './defaults';

package/src/rubrics/rubric.ts

@@ -0,0 +1,62 @@
+import type { ModerationCategory, Severity } from '../types';
+import type { RubricResult, RubricRule } from './types';
+
+const SEVERITY_ORDER: Record<Severity, number> = {
+  low: 0,
+  medium: 1,
+  high: 2,
+  critical: 3,
+};
+
+/**
+ * Composable classifier-to-action mapping.
+ *
+ * Callers hand a `ScoringRubric` their classifier output
+ * (`ModerationCategory[]`) and get back a decision: the recommended
+ * action, the aggregate severity, and the categories that contributed.
+ *
+ * Apps can use the ship-with defaults (`STRICT_RUBRIC`,
+ * `PERMISSIVE_RUBRIC`, `NSFW_ONLY_RUBRIC`) or pass custom rules.
+ *
+ * Rules are evaluated in input order; the highest-severity match wins
+ * the recommended action. Every matched category is returned in the
+ * result so callers can explain the decision.
+ */
+export class ScoringRubric {
+  constructor(private rules: RubricRule[]) {}
+
+  evaluate(categories: ModerationCategory[]): RubricResult {
+    const matched: ModerationCategory[] = [];
+    const reasons: string[] = [];
+
+    let best: RubricRule | null = null;
+
+    for (const category of categories) {
+      for (const rule of this.rules) {
+        const categoryMatches = rule.match.category === undefined || category.category.includes(rule.match.category);
+
+        if (!categoryMatches) {
+          continue;
+        }
+
+        if (category.confidence < rule.match.minConfidence) {
+          continue;
+        }
+
+        matched.push(category);
+        reasons.push(`${category.category} (${category.confidence.toFixed(0)}%) >= ${rule.match.minConfidence}% → ${rule.action}`);
+
+        if (!best || SEVERITY_ORDER[rule.severity] > SEVERITY_ORDER[best.severity]) {
+          best = rule;
+        }
+      }
+    }
+
+    return {
+      action: best?.action ?? null,
+      severity: best?.severity ?? 'low',
+      matched,
+      reasons,
+    };
+  }
+}

package/src/rubrics/types.ts

@@ -0,0 +1,30 @@
+import type { ModerationCategory, Severity } from '../types';
+import type { ActionType } from '../actions';
+
+export interface RubricMatch {
+  /**
+   * Category name to match. Omit for a wildcard that fires on any category.
+   * Matched with substring `includes`, so a rule for `sexual` also fires
+   * on compound categories like `sexual/minors`.
+   */
+  category?: string;
+  /** Minimum confidence (0-100) required for this rule to fire. */
+  minConfidence: number;
+}
+
+export interface RubricRule {
+  match: RubricMatch;
+  action: ActionType;
+  severity: Severity;
+}
+
+export interface RubricResult {
+  /** The action the highest-severity matched rule recommends. */
+  action: ActionType | null;
+  /** Aggregate severity — matches the winning rule, or `'low'` if nothing matched. */
+  severity: Severity;
+  /** Every category that matched at least one rule. */
+  matched: ModerationCategory[];
+  /** Human-readable explanations — one per matched rule. */
+  reasons: string[];
+}