@joliegg/moderation 0.6.0 → 0.8.0

package/dist/text/normalize.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeText = normalizeText;
+/**
+ * Invisible / zero-width Unicode code points that users sometimes insert
+ * between letters to bypass substring-based filters. NFKC normalization
+ * does NOT collapse these on its own, so we strip them explicitly before
+ * normalizing.
+ *
+ * - U+200B Zero-Width Space
+ * - U+200C Zero-Width Non-Joiner
+ * - U+200D Zero-Width Joiner
+ * - U+200E Left-to-Right Mark
+ * - U+200F Right-to-Left Mark
+ * - U+2060 Word Joiner
+ * - U+FEFF Zero-Width No-Break Space (BOM)
+ */
+// Matching individual zero-width code points by design (we are stripping
+// them, not joining anything). ESLint's no-misleading-character-class
+// flags this since \u200d is the Zero-Width Joiner; the warning does not
+// apply here because every code point in the class is a literal target.
+// eslint-disable-next-line no-misleading-character-class
+const ZERO_WIDTH = /[\u200b\u200c\u200d\u200e\u200f\u2060\ufeff]/gu;
+/**
+ * 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.
+ */
+function normalizeText(input) {
+    return input
+        .trim()
+        .toLowerCase()
+        .replace(ZERO_WIDTH, '')
+        .normalize('NFKC')
+        .replace(/\s+/g, ' ');
+}

package/dist/types/config.d.ts

@@ -0,0 +1,13 @@
+import type { RekognitionClientConfig } from '@aws-sdk/client-rekognition';
+export interface ModerationConfiguration {
+    aws?: RekognitionClientConfig;
+    google?: {
+        apiKey?: string;
+        keyFile?: string;
+    };
+    openai?: {
+        apiKey?: string;
+    };
+    banList?: string[];
+    urlBlackList?: string[];
+}

package/dist/types/config.js

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

package/dist/types/index.d.ts

@@ -1,16 +1,9 @@
-import { RekognitionClientConfig } from '@aws-sdk/client-rekognition';
-export interface ModerationConfiguration {
-    aws?: RekognitionClientConfig;
-    google?: {
-        apiKey?: string;
-        keyFile?: string;
-    };
-    banList?: string[];
-    urlBlackList?: string[];
-}
+export * from './config';
+export type Severity = 'low' | 'medium' | 'high' | 'critical';
 export interface ModerationCategory {
     category: string;
     confidence: number;
+    severity?: Severity;
 }
 export interface ModerationResult {
     source: string;

package/dist/types/index.js

@@ -1,2 +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("./config"), exports);

package/package.json

@@ -1,15 +1,56 @@
 {
   "name": "@joliegg/moderation",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "A set of tools for chat moderation",
   "author": "Diana Islas Ocampo",
   "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./types": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/types/index.js"
+    },
+    "./actions": {
+      "types": "./dist/actions.d.ts",
+      "default": "./dist/actions.js"
+    },
+    "./text": {
+      "types": "./dist/text/index.d.ts",
+      "default": "./dist/text/index.js"
+    },
+    "./spam": {
+      "types": "./dist/spam/index.d.ts",
+      "default": "./dist/spam/index.js"
+    },
+    "./raid": {
+      "types": "./dist/raid/index.d.ts",
+      "default": "./dist/raid/index.js"
+    },
+    "./providers/google": {
+      "types": "./dist/providers/google.d.ts",
+      "default": "./dist/providers/google.js"
+    },
+    "./providers/aws": {
+      "types": "./dist/providers/aws.d.ts",
+      "default": "./dist/providers/aws.js"
+    },
+    "./providers/webrisk": {
+      "types": "./dist/providers/webrisk.d.ts",
+      "default": "./dist/providers/webrisk.js"
+    },
+    "./package.json": "./package.json"
+  },
   "scripts": {
-    "publish": "bun build && bun docs",
+    "prepublishOnly": "bun run build && bun run docs",
     "build": "bun eslint . && rm -rf ./dist && bun tsc --declaration",
     "docs": "typedoc",
-    "test": "node test/index.js"
+    "test": "bun test",
+    "test:integration": "bun run test/integration.ts"
   },
   "engines": {
     "node": ">=20.x"
@@ -17,19 +58,19 @@
   "devDependencies": {
     "@babel/eslint-parser": "^7.28.6",
     "@eslint/js": "^10.0.1",
-    "@typescript-eslint/eslint-plugin": "^8.56.1",
-    "@typescript-eslint/parser": "^8.56.1",
-    "dotenv": "^17.3.1",
-    "eslint": "^10.0.2",
-    "typedoc": "^0.28.17",
+    "@typescript-eslint/eslint-plugin": "^8.58.2",
+    "@typescript-eslint/parser": "^8.58.2",
+    "dotenv": "^17.4.2",
+    "eslint": "^10.2.0",
+    "typedoc": "^0.28.19",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.56.1"
+    "typescript-eslint": "^8.58.2"
   },
   "dependencies": {
-    "@aws-sdk/client-rekognition": "^3.996.0",
+    "@aws-sdk/client-rekognition": "^3.1031.0",
     "@google-cloud/language": "^7.2.1",
-    "@google-cloud/speech": "^7.2.1",
-    "axios": "^1.13.5",
+    "@google-cloud/speech": "^7.3.0",
+    "axios": "^1.15.0",
     "sharp": "^0.34.5"
   },
   "files": [
@@ -40,4 +81,4 @@
     "dist/*"
   ],
   "packageManager": "bun@1.3.4"
-}
+}

package/src/actions.ts

@@ -0,0 +1,50 @@
+import type { Severity } from './types';
+
+/**
+ * Moderation actions taxonomy. These should be stable so they can be persisted
+ * as a canonical list of actions.
+ */
+export const 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',
+} as const;
+
+export type ActionType = typeof ACTION_TYPES[keyof typeof ACTION_TYPES];
+
+/** Default severity per action type. */
+export const SEVERITY_BY_ACTION: Record<ActionType, Severity> = {
+  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/src/client.ts

@@ -0,0 +1,121 @@
+import { Rekognition } from '@aws-sdk/client-rekognition';
+import { LanguageServiceClient } from '@google-cloud/language';
+import { SpeechClient } from '@google-cloud/speech';
+
+import { GoogleLanguageProvider, GoogleSpeechProvider, fetchAudio } from './providers/google';
+import { RekognitionProvider } from './providers/aws';
+import { WebRiskProvider } from './providers/webrisk';
+import URLBlackList from './data/url-blacklist.json';
+import URLShortenerList from './data/url-shorteners.json';
+
+import type { ModerationCategory, ModerationConfiguration, ModerationResult } from './types';
+
+/**
+ * Composes text / image / link / audio moderation across the configured
+ * providers.
+ */
+export class ModerationClient {
+  private googleLanguage?: GoogleLanguageProvider;
+  private googleSpeech?: GoogleSpeechProvider;
+  private aws?: RekognitionProvider;
+  private webRisk?: WebRiskProvider;
+  private banList: string[] = [];
+  private urlBlackList: string[] = [];
+
+  constructor(configuration: ModerationConfiguration) {
+    if (configuration.aws) {
+      this.aws = new RekognitionProvider(new Rekognition(configuration.aws));
+    }
+
+    if (typeof configuration.google?.keyFile === 'string') {
+      this.googleLanguage = new GoogleLanguageProvider(
+        new LanguageServiceClient({ keyFile: configuration.google.keyFile })
+      );
+
+      this.googleSpeech = new GoogleSpeechProvider(
+        new SpeechClient({ keyFile: configuration.google.keyFile })
+      );
+    }
+
+    if (typeof configuration.google?.apiKey === 'string') {
+      this.webRisk = new WebRiskProvider(configuration.google.apiKey);
+    }
+
+    if (Array.isArray(configuration.banList)) {
+      this.banList = configuration.banList;
+    }
+
+    if (Array.isArray(configuration.urlBlackList)) {
+      this.urlBlackList = configuration.urlBlackList;
+    }
+  }
+
+  async moderateText(text: string, minimumConfidence: number = 50): Promise<ModerationResult> {
+    const categories: ModerationCategory[] = [];
+    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 });
+    }
+
+    if (!this.googleLanguage) {
+      return { source: text, moderation: categories };
+    }
+
+    const googleCategories = await this.googleLanguage.moderateText(text, minimumConfidence);
+
+    return { source: text, moderation: [...categories, ...googleCategories] };
+  }
+
+  async moderateImage(url: string, minimumConfidence: number = 50): Promise<ModerationResult> {
+    if (!this.aws) {
+      return { source: url, moderation: [] };
+    }
+
+    const moderation = await this.aws.moderateImage(url, minimumConfidence);
+
+    return { source: url, moderation };
+  }
+
+  async moderateLink(url: string, allowShorteners = false): Promise<ModerationResult> {
+    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 (URLBlackList.some(u => u === domain)) {
+        return { source: url, moderation: [{ category: 'BLACK_LIST', confidence: 100 }] };
+      }
+
+      if (!allowShorteners && URLShortenerList.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: string, language: string = 'en-US', minimumConfidence: number = 50): Promise<ModerationResult> {
+    if (!this.googleSpeech) {
+      return { source: url, moderation: [] };
+    }
+
+    const buffer = await fetchAudio(url);
+    const transcription = await this.googleSpeech.transcribe(buffer, language);
+
+    return this.moderateText(transcription, minimumConfidence);
+  }
+}
+
+export default ModerationClient;

package/src/index.ts

@@ -1,277 +1,3 @@
-import axios from 'axios';
-
-import { Rekognition } from '@aws-sdk/client-rekognition';
-import { LanguageServiceClient } from '@google-cloud/language';
-import { SpeechClient, protos } from '@google-cloud/speech';
-
-import sharp from 'sharp';
-
-import URLBlackList from './url-blacklist.json';
-import URLShortenerList from './url-shorteners.json';
-
-
-import { ModerationCategory, ModerationConfiguration, ModerationResult, ThreatsResponse } from './types';
-
-
-type IRecognitionConfig = protos.google.cloud.speech.v1.IRecognitionConfig;
-
-type ISpeechRecognitionResult = protos.google.cloud.speech.v1.ISpeechRecognitionResult;
-
-const MAX_IMAGE_SIZE = 5 * 1024 * 1024; // 5MB in bytes for Rekognition limit
-
-/**
- * Moderation Client
- *
- * @class ModerationClient
- */
-class ModerationClient {
-
-  private rekognitionClient?: Rekognition;
-  private googleLanguageClient?: LanguageServiceClient;
-  private googleSpeechClient?: SpeechClient;
-  private googleAPIKey?: string;
-  private banList?: string[] = [];
-  private urlBlackList?: string[] = [];
-
-  /**
-   *
-   * @param {ModerationConfiguration} configuration
-   */
-  constructor (configuration: ModerationConfiguration) {
-    if (configuration.aws) {
-      this.rekognitionClient = new Rekognition(configuration.aws);
-    }
-
-    if (typeof configuration.google?.keyFile === 'string') {
-      this.googleLanguageClient = new LanguageServiceClient({ keyFile: configuration.google.keyFile });
-      this.googleSpeechClient = new 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: string, minimumConfidence: number = 50): Promise<ModerationResult> {
-    const categories: ModerationCategory[] = [];
-
-    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: string, minimumConfidence: number = 50): Promise<ModerationResult> {
-    if (typeof this.rekognitionClient === 'undefined') {
-      return { source: url, moderation: [] };
-    }
-
-    const { data } = await axios.get<string>(url, { responseType: 'arraybuffer' });
-
-    let buffer: Buffer;
-
-    // GIFs will be split into frames
-    if (url.toLowerCase().indexOf('.gif') > -1) {
-      buffer = await sharp(data, { pages: -1 }).toFormat('png').toBuffer();
-    } else if (url.toLowerCase().indexOf('.webp') > -1) {
-      buffer = await sharp(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 sharp(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 sharp(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: string, allowShorteners = false): Promise<ModerationResult> {
-    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 = URLBlackList.some(u => u === domain);
-
-      if (globallyBlacklisted) {
-        return { source: url, moderation: [{ category: 'BLACK_LIST', confidence: 100 }] };
-      }
-
-      if (!allowShorteners) {
-        const isShortened = URLShortenerList.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.get<ThreatsResponse>(`${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: string, language: string = 'en-US', minimumConfidence: number = 50): Promise<ModerationResult> {
-    if (typeof this.googleSpeechClient === 'undefined') {
-      return { source: url, moderation: [] };
-    }
-
-    const { data } = await axios.get<string>(url, { responseType: 'arraybuffer' });
-
-
-    const options: IRecognitionConfig = {
-      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: ISpeechRecognitionResult) => result.alternatives?.at(0)?.transcript ?? '').join(' ');
-
-    return this.moderateText(transcription, minimumConfidence);
-  }
-
-}
-
-export default ModerationClient;
+export { ModerationClient, default } from './client';
+export * from './types';
+export * from './actions';