@joliegg/moderation 0.6.0 → 0.9.0

package/dist/index.js

@@ -1,218 +1,25 @@
 "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);
+};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-const axios_1 = __importDefault(require("axios"));
-const client_rekognition_1 = require("@aws-sdk/client-rekognition");
-const language_1 = require("@google-cloud/language");
-const speech_1 = require("@google-cloud/speech");
-const sharp_1 = __importDefault(require("sharp"));
-const url_blacklist_json_1 = __importDefault(require("./url-blacklist.json"));
-const url_shorteners_json_1 = __importDefault(require("./url-shorteners.json"));
-const MAX_IMAGE_SIZE = 5 * 1024 * 1024; // 5MB in bytes for Rekognition limit
-/**
- * Moderation Client
- *
- * @class ModerationClient
- */
-class ModerationClient {
-    rekognitionClient;
-    googleLanguageClient;
-    googleSpeechClient;
-    googleAPIKey;
-    banList = [];
-    urlBlackList = [];
-    /**
-     *
-     * @param {ModerationConfiguration} configuration
-     */
-    constructor(configuration) {
-        if (configuration.aws) {
-            this.rekognitionClient = new client_rekognition_1.Rekognition(configuration.aws);
-        }
-        if (typeof configuration.google?.keyFile === 'string') {
-            this.googleLanguageClient = new language_1.LanguageServiceClient({ keyFile: configuration.google.keyFile });
-            this.googleSpeechClient = new speech_1.SpeechClient({ keyFile: configuration.google.keyFile });
-        }
-        if (typeof configuration.google?.apiKey === 'string') {
-            this.googleAPIKey = configuration.google.apiKey;
-        }
-        if (Array.isArray(configuration.banList)) {
-            this.banList = configuration.banList;
-        }
-        if (Array.isArray(configuration.urlBlackList)) {
-            this.urlBlackList = configuration.urlBlackList;
-        }
-    }
-    /**
-     * 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
-     */
-    async moderateText(text, minimumConfidence = 50) {
-        const categories = [];
-        if (Array.isArray(this.banList)) {
-            const normalizedText = text.toLowerCase();
-            const matches = this.banList.filter(w => normalizedText.indexOf(w) > -1);
-            if (matches.length > 0) {
-                const words = normalizedText.split(' ');
-                categories.push({
-                    category: 'BAN_LIST',
-                    confidence: (matches.length / words.length) * 100,
-                });
-            }
-        }
-        if (typeof this.googleLanguageClient === 'undefined') {
-            return { source: text, moderation: categories };
-        }
-        const [result] = await this.googleLanguageClient.moderateText({
-            document: {
-                content: text,
-                type: 'PLAIN_TEXT',
-            },
-        });
-        if (result && 'moderationCategories' in result) {
-            if (Array.isArray(result.moderationCategories)) {
-                const results = result.moderationCategories.map(c => ({
-                    category: c.name ?? 'Unknown',
-                    confidence: (c.confidence ?? 0) * 100,
-                })).filter(c => c.confidence >= minimumConfidence);
-                return { source: text, moderation: [...categories, ...results] };
-            }
-        }
-        return { source: text, moderation: [] };
-    }
-    /**
-     * 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
-     */
-    async moderateImage(url, minimumConfidence = 50) {
-        if (typeof this.rekognitionClient === 'undefined') {
-            return { source: url, moderation: [] };
-        }
-        const { data } = await axios_1.default.get(url, { responseType: 'arraybuffer' });
-        let buffer;
-        // GIFs will be split into frames
-        if (url.toLowerCase().indexOf('.gif') > -1) {
-            buffer = await (0, sharp_1.default)(data, { pages: -1 }).toFormat('png').toBuffer();
-        }
-        else if (url.toLowerCase().indexOf('.webp') > -1) {
-            buffer = await (0, sharp_1.default)(data).toFormat('png').toBuffer();
-        }
-        else {
-            // Download image as binary data
-            buffer = Buffer.from(data, 'binary');
-        }
-        // Ensure image is not larger than 5MB (Rekognition limit)
-        if (buffer.length > MAX_IMAGE_SIZE) {
-            try {
-                // Calculate new dimensions to reduce size
-                const metadata = await (0, sharp_1.default)(buffer).metadata();
-                const { width, height } = metadata;
-                if (typeof width !== 'number' || typeof height !== 'number') {
-                    throw new Error('Invalid image metadata');
-                }
-                // Calculate the scaling factor
-                const scalingFactor = Math.sqrt(MAX_IMAGE_SIZE / buffer.length);
-                // Calculate new dimensions
-                const newWidth = Math.floor(width * scalingFactor);
-                const newHeight = Math.floor(height * scalingFactor);
-                const resizedBuffer = await (0, sharp_1.default)(buffer)
-                    .resize(Math.round(newWidth), Math.round(newHeight))
-                    .toBuffer();
-                buffer = resizedBuffer;
-            }
-            catch {
-                // We can't resize the image. We'll skip the resize and try to process it as is
-            }
-        }
-        const { ModerationLabels } = await this.rekognitionClient.detectModerationLabels({
-            Image: {
-                Bytes: buffer
-            },
-            MinConfidence: minimumConfidence
-        });
-        if (Array.isArray(ModerationLabels)) {
-            const moderation = ModerationLabels.map(l => ({
-                category: l.Name ?? 'Unknown',
-                confidence: l.Confidence ?? 0,
-            }));
-            return { source: url, moderation };
-        }
-        return { source: url, moderation: [] };
-    }
-    async moderateLink(url, allowShorteners = false) {
-        try {
-            const domain = new URL(url).hostname;
-            const blacklisted = this.urlBlackList?.some(u => u.indexOf(url) > -1);
-            if (blacklisted) {
-                return { source: url, moderation: [{ category: 'CUSTOM_BLACK_LIST', confidence: 100 }] };
-            }
-            const globallyBlacklisted = url_blacklist_json_1.default.some(u => u === domain);
-            if (globallyBlacklisted) {
-                return { source: url, moderation: [{ category: 'BLACK_LIST', confidence: 100 }] };
-            }
-            if (!allowShorteners) {
-                const isShortened = url_shorteners_json_1.default.some(u => u === domain);
-                if (isShortened) {
-                    return { source: url, moderation: [{ category: 'URL_SHORTENER', confidence: 100 }] };
-                }
-            }
-        }
-        catch {
-            // Invalid URL
-            return { source: url, moderation: [] };
-        }
-        if (typeof this.googleAPIKey !== 'string') {
-            return { source: url, moderation: [] };
-        }
-        const types = [
-            'MALWARE',
-            'SOCIAL_ENGINEERING',
-            'UNWANTED_SOFTWARE',
-            'SOCIAL_ENGINEERING_EXTENDED_COVERAGE'
-        ];
-        const threatTypes = types.join('&threatTypes=');
-        const requestUrl = `https://webrisk.googleapis.com/v1/uris:search?threatTypes=${threatTypes}&key=${this.googleAPIKey}`;
-        const { data } = await axios_1.default.get(`${requestUrl}&uri=${encodeURIComponent(url)}`);
-        const threats = data?.threat?.threatTypes;
-        if (Array.isArray(threats)) {
-            const moderation = threats.map(t => ({
-                category: t,
-                confidence: 100,
-            }));
-            return { source: url, moderation };
-        }
-        return { source: url, moderation: [] };
-    }
-    async moderateAudio(url, language = 'en-US', minimumConfidence = 50) {
-        if (typeof this.googleSpeechClient === 'undefined') {
-            return { source: url, moderation: [] };
-        }
-        const { data } = await axios_1.default.get(url, { responseType: 'arraybuffer' });
-        const options = {
-            encoding: 'OGG_OPUS',
-            sampleRateHertz: 48000,
-            languageCode: language,
-        };
-        const [response] = await this.googleSpeechClient.recognize({
-            audio: { content: Buffer.from(data, 'binary').toString('base64') },
-            config: options,
-        });
-        if (!Array.isArray(response?.results)) {
-            return { source: url, moderation: [] };
-        }
-        const transcription = response?.results?.map((result) => result.alternatives?.at(0)?.transcript ?? '').join(' ');
-        return this.moderateText(transcription, minimumConfidence);
-    }
-}
-exports.default = ModerationClient;
+exports.default = exports.ModerationClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "ModerationClient", { enumerable: true, get: function () { return client_1.ModerationClient; } });
+Object.defineProperty(exports, "default", { enumerable: true, get: function () { return __importDefault(client_1).default; } });
+__exportStar(require("./types"), exports);
+__exportStar(require("./actions"), exports);

package/dist/providers/aws.d.ts

@@ -0,0 +1,11 @@
+import { Rekognition } from '@aws-sdk/client-rekognition';
+import type { ModerationCategory } from '../types';
+/**
+ * AWS Rekognition image moderation adapter. Handles GIF and WEBP
+ * conversion to PNG and downscales images over the 5 MB Rekognition limit.
+ */
+export declare class RekognitionProvider {
+    private client;
+    constructor(client: Rekognition);
+    moderateImage(url: string, minimumConfidence: number): Promise<ModerationCategory[]>;
+}

package/dist/providers/aws.js

@@ -0,0 +1,58 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RekognitionProvider = void 0;
+const axios_1 = __importDefault(require("axios"));
+const sharp_1 = __importDefault(require("sharp"));
+// AWS Rekognition 5MB inline-image limit
+const MAX_IMAGE_SIZE = 5 * 1024 * 1024;
+/**
+ * AWS Rekognition image moderation adapter. Handles GIF and WEBP
+ * conversion to PNG and downscales images over the 5 MB Rekognition limit.
+ */
+class RekognitionProvider {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async moderateImage(url, minimumConfidence) {
+        const { data } = await axios_1.default.get(url, { responseType: 'arraybuffer' });
+        let buffer;
+        const lowered = url.toLowerCase();
+        if (lowered.includes('.gif')) {
+            buffer = await (0, sharp_1.default)(Buffer.from(data), { pages: -1 }).toFormat('png').toBuffer();
+        }
+        else if (lowered.includes('.webp')) {
+            buffer = await (0, sharp_1.default)(Buffer.from(data)).toFormat('png').toBuffer();
+        }
+        else {
+            buffer = Buffer.from(data);
+        }
+        if (buffer.length > MAX_IMAGE_SIZE) {
+            try {
+                const metadata = await (0, sharp_1.default)(buffer).metadata();
+                const { width, height } = metadata;
+                if (typeof width === 'number' && typeof height === 'number') {
+                    const scalingFactor = Math.sqrt(MAX_IMAGE_SIZE / buffer.length);
+                    buffer = await (0, sharp_1.default)(buffer)
+                        .resize(Math.round(width * scalingFactor), Math.round(height * scalingFactor))
+                        .toBuffer();
+                }
+            }
+            catch {
+                // Resize failed, we will use the original buffer.
+            }
+        }
+        const { ModerationLabels } = await this.client.detectModerationLabels({
+            Image: { Bytes: buffer },
+            MinConfidence: minimumConfidence,
+        });
+        if (Array.isArray(ModerationLabels)) {
+            return ModerationLabels.map(l => ({ category: l.Name ?? 'Unknown', confidence: l.Confidence ?? 0 }));
+        }
+        return [];
+    }
+}
+exports.RekognitionProvider = RekognitionProvider;

package/dist/providers/google.d.ts

@@ -0,0 +1,21 @@
+import { LanguageServiceClient } from '@google-cloud/language';
+import { SpeechClient } from '@google-cloud/speech';
+import type { ModerationCategory } from '../types';
+/**
+ * Google Cloud Natural Language moderation adapter.
+ */
+export declare class GoogleLanguageProvider {
+    private client;
+    constructor(client: LanguageServiceClient);
+    moderateText(text: string, minimumConfidence: number): Promise<ModerationCategory[]>;
+}
+/**
+ * Google Cloud Speech-to-Text adapter. Used for audio transcription
+ * before running the transcript through text moderation.
+ */
+export declare class GoogleSpeechProvider {
+    private client;
+    constructor(client: SpeechClient);
+    transcribe(audioBuffer: Buffer, languageCode: string): Promise<string>;
+}
+export declare function fetchAudio(url: string): Promise<Buffer>;

package/dist/providers/google.js

@@ -0,0 +1,61 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GoogleSpeechProvider = exports.GoogleLanguageProvider = void 0;
+exports.fetchAudio = fetchAudio;
+const axios_1 = __importDefault(require("axios"));
+/**
+ * Google Cloud Natural Language moderation adapter.
+ */
+class GoogleLanguageProvider {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async moderateText(text, minimumConfidence) {
+        const [result] = await this.client.moderateText({
+            document: { content: text, type: 'PLAIN_TEXT' },
+        });
+        if (!result || !('moderationCategories' in result) || !Array.isArray(result.moderationCategories)) {
+            return [];
+        }
+        return result.moderationCategories
+            .map(c => ({ category: c.name ?? 'Unknown', confidence: (c.confidence ?? 0) * 100 }))
+            .filter(c => c.confidence >= minimumConfidence);
+    }
+}
+exports.GoogleLanguageProvider = GoogleLanguageProvider;
+/**
+ * Google Cloud Speech-to-Text adapter. Used for audio transcription
+ * before running the transcript through text moderation.
+ */
+class GoogleSpeechProvider {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async transcribe(audioBuffer, languageCode) {
+        const config = {
+            encoding: 'OGG_OPUS',
+            sampleRateHertz: 48000,
+            languageCode,
+        };
+        const [response] = await this.client.recognize({
+            audio: { content: audioBuffer.toString('base64') },
+            config,
+        });
+        if (!Array.isArray(response?.results)) {
+            return '';
+        }
+        return response.results
+            .map((r) => r.alternatives?.at(0)?.transcript ?? '')
+            .join(' ');
+    }
+}
+exports.GoogleSpeechProvider = GoogleSpeechProvider;
+async function fetchAudio(url) {
+    const { data } = await axios_1.default.get(url, { responseType: 'arraybuffer' });
+    return Buffer.from(data);
+}

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/providers/webrisk.d.ts

@@ -0,0 +1,9 @@
+import type { ModerationCategory } from '../types';
+/**
+ * Google Web Risk link moderation adapter.
+ */
+export declare class WebRiskProvider {
+    private apiKey;
+    constructor(apiKey: string);
+    checkLink(url: string): Promise<ModerationCategory[]>;
+}

package/dist/providers/webrisk.js

@@ -0,0 +1,33 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebRiskProvider = void 0;
+const axios_1 = __importDefault(require("axios"));
+const THREAT_TYPES = [
+    'MALWARE',
+    'SOCIAL_ENGINEERING',
+    'UNWANTED_SOFTWARE',
+    'SOCIAL_ENGINEERING_EXTENDED_COVERAGE',
+];
+/**
+ * Google Web Risk link moderation adapter.
+ */
+class WebRiskProvider {
+    apiKey;
+    constructor(apiKey) {
+        this.apiKey = apiKey;
+    }
+    async checkLink(url) {
+        const threatTypes = THREAT_TYPES.join('&threatTypes=');
+        const requestUrl = `https://webrisk.googleapis.com/v1/uris:search?threatTypes=${threatTypes}&key=${this.apiKey}`;
+        const { data } = await axios_1.default.get(`${requestUrl}&uri=${encodeURIComponent(url)}`);
+        const threats = data?.threat?.threatTypes;
+        if (Array.isArray(threats)) {
+            return threats.map(t => ({ category: t, confidence: 100 }));
+        }
+        return [];
+    }
+}
+exports.WebRiskProvider = WebRiskProvider;

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;
+}