🛡️ Zodiac Guard SDK

A lightweight, high-performance content moderation SDK for Node.js. Protect your community from profanity, threats, and spam while tracking user risk in real-time.

🚀 Quick Start

1. Installation

npm install zodiac-guard

2. Initialization

The SDK supports both modern ES Modules and legacy CommonJS.

// ES Modules (Next.js, Vite, Node 20+)
import Zodiac from "zodiac-guard";

// CommonJS (Standard Node.js)
// const Zodiac = require("zodiac-guard");

const zodiac = new Zodiac(process.env.ZODIAC_API_KEY);

3. Usage

To ensure accurate User Risk Scoring, the senderId is required for every check.

const result = await zodiac.check("fuck u", {
  mode: "community", // Optional: 'community', 'dating', 'kids', 'marketplace'
  metadata: {
    senderId: "user_8821", // REQUIRED for tracking history
    platform: "web-app",
  },
});

console.log(result);
/* {
  isSafe: false,
  reason: 'Profanity',
  reportId: '54b24b8f-a538-422b-ab8b-f3f30c00a2a9',
  userRiskScore: 0.4
} 
*/

📊 Features & Logic

🛡️ Fail-Safe Architecture

Production stability is our priority. If your API key expires, the service times out, or a network error occurs, the SDK defaults to isSafe: true. This ensures your application never crashes or blocks users due to external service interruptions.

const result = await zodiac.check("text", { metadata: { senderId: "system" } });

if (result.error) {
  console.warn(
    "Moderation service unavailable, defaulting to safe:",
    result.error,
  );
}

🎯 Moderation Modes

• COMMUNITY (Default): Standard toxicity, hate speech, and harassment detection.
• KIDS: Zero-tolerance for profanity, violence, or mature themes.
• DATING: Allows flirting/socializing but blocks threats and harassment.
• MARKETPLACE: Specialized detection for scams and phishing links.

📈 User Risk Scoring

Zodiac automatically calculates a risk profile for every senderId based on their violation history.

• 0.2 – 0.4 (Low Risk): First-time violations. Typically triggers a warning.
• 0.6 – 0.8 (Medium Risk): Repeat offender. Recommended: mute or shadow-ban.
• 1.0 (Critical Risk): Persistent violator. Recommended: permanent account ban.

📡 API Reference

new Zodiac(apiKey, [baseUrl])

• apiKey: Your Zodiac Guard API Key.
• baseUrl: (Optional) Defaults to https://zodiac-api-five.vercel.app.

zodiac.check(text, options)

• text: The string to moderate.
• options.metadata.senderId: Required. String ID of the message author.
• options.mode: Optional. The filter mode to apply.