@helyx/module-automod 1.0.1

package/migrations/0001_automod_standard.sql

@@ -0,0 +1,114 @@
+CREATE TABLE IF NOT EXISTS automod_rules (
+  rule_id uuid PRIMARY KEY,
+  guild_id text NOT NULL CHECK (guild_id ~ '^[0-9]{17,20}$'),
+  name text NOT NULL CHECK (char_length(name) BETWEEN 1 AND 80),
+  name_key text NOT NULL CHECK (char_length(name_key) BETWEEN 1 AND 80),
+  category text NOT NULL CHECK (category IN ('low', 'medium', 'high', 'critical')),
+  rule_kind text NOT NULL CHECK (rule_kind IN ('keyword', 'keyword_preset', 'spam', 'mention_spam')),
+  status text NOT NULL CHECK (status IN ('draft', 'published', 'disabled', 'drifted', 'missing', 'review')),
+  document_json jsonb NOT NULL CHECK (jsonb_typeof(document_json) = 'object'),
+  native_rule_id text CHECK (native_rule_id IS NULL OR native_rule_id ~ '^[0-9]{17,20}$'),
+  native_fingerprint text CHECK (native_fingerprint IS NULL OR native_fingerprint ~ '^[a-f0-9]{64}$'),
+  operation_key text NOT NULL CHECK (char_length(operation_key) BETWEEN 1 AND 200),
+  configuration_revision text NOT NULL CHECK (char_length(configuration_revision) BETWEEN 1 AND 200),
+  revision integer NOT NULL CHECK (revision >= 1),
+  created_by_user_id text CHECK (created_by_user_id IS NULL OR created_by_user_id ~ '^[0-9]{17,20}$'),
+  updated_by_user_id text CHECK (updated_by_user_id IS NULL OR updated_by_user_id ~ '^[0-9]{17,20}$'),
+  created_at timestamptz NOT NULL,
+  updated_at timestamptz NOT NULL,
+  UNIQUE (guild_id, rule_id),
+  UNIQUE (guild_id, name_key),
+  UNIQUE (guild_id, native_rule_id),
+  CHECK (updated_at >= created_at),
+  CHECK ((native_rule_id IS NULL) = (native_fingerprint IS NULL))
+);
+
+CREATE INDEX IF NOT EXISTS automod_rules_guild_updated_idx
+  ON automod_rules (guild_id, updated_at DESC, rule_id DESC);
+CREATE INDEX IF NOT EXISTS automod_rules_guild_status_idx
+  ON automod_rules (guild_id, status, updated_at DESC, rule_id DESC);
+
+CREATE TABLE IF NOT EXISTS automod_enforcement_claims (
+  claim_key text NOT NULL CHECK (claim_key ~ '^[a-f0-9]{64}$'),
+  guild_id text NOT NULL CHECK (guild_id ~ '^[0-9]{17,20}$'),
+  rule_id uuid NOT NULL,
+  rule_revision integer NOT NULL CHECK (rule_revision >= 1),
+  configuration_revision text NOT NULL CHECK (char_length(configuration_revision) BETWEEN 1 AND 200),
+  subject_user_id text CHECK (subject_user_id IS NULL OR subject_user_id ~ '^[0-9]{17,20}$'),
+  channel_id text CHECK (channel_id IS NULL OR channel_id ~ '^[0-9]{17,20}$'),
+  message_id text CHECK (message_id IS NULL OR message_id ~ '^[0-9]{17,20}$'),
+  category text NOT NULL CHECK (category IN ('low', 'medium', 'high', 'critical')),
+  action_family text NOT NULL CHECK (char_length(action_family) BETWEEN 1 AND 100),
+  source text NOT NULL CHECK (source IN ('native', 'enhanced')),
+  request_fingerprint text NOT NULL CHECK (request_fingerprint ~ '^[a-f0-9]{64}$'),
+  moderation_case_id uuid,
+  repeat_ordinal smallint CHECK (repeat_ordinal IS NULL OR repeat_ordinal BETWEEN 1 AND 3),
+  selected_action text CHECK (selected_action IS NULL OR selected_action IN ('case_only', 'delete_message', 'warn', 'timeout', 'kick', 'ban', 'demote')),
+  outcome text NOT NULL CHECK (outcome IN ('pending', 'applied', 'already_applied', 'native_only', 'rejected', 'failed', 'ambiguous', 'review_required')),
+  safe_code text CHECK (safe_code IS NULL OR char_length(safe_code) BETWEEN 1 AND 100),
+  revision integer NOT NULL CHECK (revision >= 1),
+  occurred_at timestamptz NOT NULL,
+  settled_at timestamptz,
+  retention_expires_at timestamptz NOT NULL,
+  created_at timestamptz NOT NULL,
+  updated_at timestamptz NOT NULL,
+  PRIMARY KEY (guild_id, claim_key),
+  FOREIGN KEY (guild_id, rule_id) REFERENCES automod_rules(guild_id, rule_id) ON DELETE RESTRICT,
+  CHECK (updated_at >= created_at),
+  CHECK ((settled_at IS NULL) = (outcome = 'pending')),
+  CHECK (retention_expires_at >= occurred_at + INTERVAL '90 days')
+);
+
+CREATE INDEX IF NOT EXISTS automod_claims_subject_rule_idx
+  ON automod_enforcement_claims (guild_id, subject_user_id, rule_id, occurred_at DESC)
+  WHERE subject_user_id IS NOT NULL;
+CREATE INDEX IF NOT EXISTS automod_claims_retention_idx
+  ON automod_enforcement_claims (retention_expires_at, claim_key)
+  WHERE outcome <> 'pending';
+
+CREATE TABLE IF NOT EXISTS automod_action_receipts (
+  receipt_id uuid PRIMARY KEY,
+  guild_id text NOT NULL CHECK (guild_id ~ '^[0-9]{17,20}$'),
+  event_key text NOT NULL CHECK (char_length(event_key) BETWEEN 1 AND 200),
+  rule_id uuid NOT NULL,
+  rule_revision integer NOT NULL CHECK (rule_revision >= 1),
+  configuration_revision text NOT NULL CHECK (char_length(configuration_revision) BETWEEN 1 AND 200),
+  native_rule_id text NOT NULL CHECK (native_rule_id ~ '^[0-9]{17,20}$'),
+  subject_user_id text CHECK (subject_user_id IS NULL OR subject_user_id ~ '^[0-9]{17,20}$'),
+  channel_id text CHECK (channel_id IS NULL OR channel_id ~ '^[0-9]{17,20}$'),
+  message_id text CHECK (message_id IS NULL OR message_id ~ '^[0-9]{17,20}$'),
+  alert_system_message_id text CHECK (alert_system_message_id IS NULL OR alert_system_message_id ~ '^[0-9]{17,20}$'),
+  action_type text NOT NULL CHECK (action_type IN ('block_message', 'send_alert_message', 'timeout')),
+  claim_key text NOT NULL CHECK (claim_key ~ '^[a-f0-9]{64}$'),
+  moderation_case_id uuid,
+  outcome text NOT NULL CHECK (outcome IN ('observed', 'applied', 'already_applied', 'native_only', 'rejected', 'failed', 'ambiguous', 'review_required')),
+  safe_code text CHECK (safe_code IS NULL OR char_length(safe_code) BETWEEN 1 AND 100),
+  occurred_at timestamptz NOT NULL,
+  retention_expires_at timestamptz NOT NULL,
+  created_at timestamptz NOT NULL,
+  UNIQUE (guild_id, event_key),
+  FOREIGN KEY (guild_id, rule_id) REFERENCES automod_rules(guild_id, rule_id) ON DELETE RESTRICT,
+  FOREIGN KEY (guild_id, claim_key) REFERENCES automod_enforcement_claims(guild_id, claim_key) DEFERRABLE INITIALLY DEFERRED,
+  CHECK (retention_expires_at >= occurred_at + INTERVAL '90 days')
+);
+
+CREATE INDEX IF NOT EXISTS automod_receipts_guild_occurred_idx
+  ON automod_action_receipts (guild_id, occurred_at DESC, receipt_id DESC);
+CREATE INDEX IF NOT EXISTS automod_receipts_subject_idx
+  ON automod_action_receipts (guild_id, subject_user_id, occurred_at DESC)
+  WHERE subject_user_id IS NOT NULL;
+
+CREATE TABLE IF NOT EXISTS automod_daily_counts (
+  guild_id text NOT NULL CHECK (guild_id ~ '^[0-9]{17,20}$'),
+  rule_id uuid NOT NULL,
+  day date NOT NULL,
+  source text NOT NULL CHECK (source IN ('native', 'enhanced')),
+  action_type text NOT NULL CHECK (char_length(action_type) BETWEEN 1 AND 50),
+  observed_count bigint NOT NULL DEFAULT 0 CHECK (observed_count >= 0),
+  last_observed_at timestamptz NOT NULL,
+  PRIMARY KEY (guild_id, rule_id, day, source, action_type),
+  FOREIGN KEY (guild_id, rule_id) REFERENCES automod_rules(guild_id, rule_id) ON DELETE RESTRICT
+);
+
+CREATE INDEX IF NOT EXISTS automod_daily_counts_day_idx
+  ON automod_daily_counts (day DESC, guild_id);

package/migrations/0002_automod_enhanced_receipts.sql

@@ -0,0 +1,40 @@
+ALTER TABLE automod_action_receipts
+  ALTER COLUMN native_rule_id DROP NOT NULL;
+
+ALTER TABLE automod_action_receipts
+  ADD COLUMN IF NOT EXISTS source text NOT NULL DEFAULT 'native',
+  ADD COLUMN IF NOT EXISTS detector_version text,
+  ADD COLUMN IF NOT EXISTS scoring_version text,
+  ADD COLUMN IF NOT EXISTS term_id text,
+  ADD COLUMN IF NOT EXISTS detection_method text,
+  ADD COLUMN IF NOT EXISTS confidence_class text,
+  ADD COLUMN IF NOT EXISTS confidence_score smallint,
+  ADD COLUMN IF NOT EXISTS effective_threshold smallint,
+  ADD COLUMN IF NOT EXISTS correlation_id uuid;
+
+ALTER TABLE automod_action_receipts
+  DROP CONSTRAINT IF EXISTS automod_action_receipts_action_type_check;
+ALTER TABLE automod_action_receipts
+  ADD CONSTRAINT automod_action_receipts_action_type_check
+  CHECK (action_type IN ('block_message', 'send_alert_message', 'timeout', 'detection'));
+
+ALTER TABLE automod_action_receipts
+  ADD CONSTRAINT automod_action_receipts_source_check
+  CHECK (source IN ('native', 'enhanced')),
+  ADD CONSTRAINT automod_action_receipts_enhanced_shape_check
+  CHECK (
+    (source = 'native' AND action_type <> 'detection' AND native_rule_id IS NOT NULL) OR
+    (source = 'enhanced' AND action_type = 'detection' AND native_rule_id IS NULL AND
+      detector_version IS NOT NULL AND scoring_version IS NOT NULL AND
+      term_id IS NOT NULL AND detection_method IS NOT NULL AND
+      confidence_class IS NOT NULL AND confidence_score BETWEEN 0 AND 100 AND
+      effective_threshold BETWEEN 0 AND 100 AND correlation_id IS NOT NULL)
+  );
+
+CREATE INDEX IF NOT EXISTS automod_receipts_case_idx
+  ON automod_action_receipts (guild_id, moderation_case_id)
+  WHERE moderation_case_id IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS automod_claims_case_idx
+  ON automod_enforcement_claims (guild_id, moderation_case_id)
+  WHERE moderation_case_id IS NOT NULL;

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@helyx/module-automod",
+  "version": "1.0.1",
+  "description": "Manage transparent Discord-native Auto Moderation rules and structural enforcement receipts.",
+  "keywords": [
+    "helyx",
+    "discord",
+    "auto-moderation",
+    "module"
+  ],
+  "private": false,
+  "license": "HSAL 1.0",
+  "homepage": "https://helyx.gg/modules/",
+  "bugs": {
+    "url": "https://github.com/ZyC0R3/Helyx/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ZyC0R3/Helyx.git",
+    "directory": "modules/automod"
+  },
+  "engines": {
+    "node": ">=24 <27",
+    "npm": ">=11"
+  },
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "files": [
+    "dist",
+    "!dist/*.tsbuildinfo",
+    "!dist/**/*.map",
+    "migrations",
+    "manifest.json",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./engine": {
+      "types": "./dist/engine/index.d.ts",
+      "default": "./dist/engine/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "vitest run --root ../.. modules/automod/tests"
+  },
+  "dependencies": {
+    "@helyx/module-manifest": ">=0.11.0 <0.12.0",
+    "@helyx/sdk": ">=0.13.0 <0.14.0",
+    "zod": "4.4.3"
+  }
+}