Respectify TypeScript Client

A TypeScript client library for the Respectify API, providing comment moderation, spam detection, toxicity analysis, and dogwhistle detection.

Respectify aims to be more than comment moderation: it tries to teach and edify users when a comment is rejected.

For bloggers, companies with articles, etc it provides a way to keep discourse civil and on-topic without censorship.

Installation

npm install respectify

Requires Node.js 18 or later.

Quick Start

import { RespectifyClient } from "respectify";

const client = new RespectifyClient({
  email: "[email protected]",
  apiKey: "your-api-key",
});

// Initialize a topic — comments are evaluated in the context of an article/post
const topic = await client.initTopicFromText("This is my article content...");
const articleId = topic.article_id;

// Evaluate comment quality and toxicity
const score = await client.evaluateComment("This is a thoughtful comment", articleId);
console.log(`Quality: ${score.overall_score}/5, Toxicity: ${score.toxicity_score.toFixed(2)}`);

// Check if a comment is spam
const spam = await client.checkSpam("Great post!", articleId);
console.log(`Is spam: ${spam.is_spam}`);

// Perspective-compatible scoring for migrations from Google's Perspective API
const perspective = await client.perspective.analyzeComment({
  comment: { text: "You clearly did not read the article." },
  requestedAttributes: {
    TOXICITY: {},
    INSULT: {},
  },
});
console.log(perspective.attributeScores.TOXICITY.summaryScore.value);

Megacall for Efficiency

Perform multiple analyses in a single API call:

const result = await client.megacall({
  comment: "Test comment",
  articleId, // from initTopicFromText() or initTopicFromUrl()
  includeSpam: true,
  includeRelevance: true,
  includeCommentScore: true,
  includeDogwhistle: true,
  bannedTopics: ["politics"],
});

console.log(`Spam: ${result.spam_check?.is_spam}`);
console.log(`Quality: ${result.comment_score?.overall_score}/5`);
console.log(`On topic: ${result.relevance_check?.on_topic.on_topic}`);
console.log(`Dogwhistles: ${result.dogwhistle_check?.detection.dogwhistles_detected}`);

API Reference

Client Options

const client = new RespectifyClient({
  email: "[email protected]", // Required
  apiKey: "your-api-key",          // Required
  baseUrl: "https://...",          // Optional, defaults to production
  version: "0.2",                  // Optional, defaults to "0.2"
  timeout: 30000,                  // Optional, milliseconds, defaults to 30000
  website: "myblog.com",           // Optional, for license tracking
});

Methods

Topic Management:

• initTopicFromText(text, topicDescription?) — Initialize a topic from text content
• initTopicFromUrl(url, topicDescription?) — Initialize a topic from a URL

Comment Analysis:

• evaluateComment(comment, articleId, replyToComment?) — Quality and toxicity scoring
• checkSpam(comment, articleId?) — Spam detection (articleId optional)
• checkRelevance(comment, articleId, bannedTopics?) — Relevance and banned topic detection
• checkDogwhistle(comment, articleId, sensitiveTopics?, dogwhistleExamples?) — Dogwhistle detection

Batch Operations:

• megacall(options) — Multiple analyses in a single API call

Perspective Compatibility:

• client.perspective.analyzeComment(request) — Public Perspective-compatible analyzeComment wrapper
• client.perspective.suggestCommentScore(request) — Public Perspective-compatible suggestCommentScore wrapper

Authentication:

• checkUserCredentials() — Verify API credentials and subscription status

Error Handling

import {
  RespectifyError,           // Base error
  AuthenticationError,       // Invalid credentials (401)
  BadRequestError,           // Invalid parameters (400)
  PaymentRequiredError,      // Subscription required (402)
  UnsupportedMediaTypeError, // Wrong content type (415)
  ServerError,               // Server issues (500+)
  ResponseParseError,        // Malformed API response
} from "respectify";

try {
  const result = await client.checkSpam("test", articleId);
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error("Check your API credentials");
  } else if (error instanceof PaymentRequiredError) {
    console.error("This feature requires a paid plan");
  } else if (error instanceof BadRequestError) {
    console.error(`Invalid request: ${error.message}`);
  }
}

All errors include statusCode and responseData properties for debugging.

Response Sanitization

All string values in API responses are automatically HTML-encoded to prevent XSS. API responses echo back user-submitted comment text (in quoted fallacies, objectionable phrases, etc.) so this encoding is applied by default to make responses safe to render in HTML.

Development

Running Tests

Create a repo-level .env file with your credentials:

[email protected]
RESPECTIFY_API_KEY=your-api-key

npm install
npm test              # Run all tests (unit + integration)
npm run test:watch    # Watch mode
npm run typecheck     # Type checking only
npm run build         # Build for distribution

Requirements

• Node.js >= 18 (uses native fetch)
• One runtime dependency: escape-html for response sanitization

License

MIT — see LICENSE for details.

Links

• Respectify
• API Documentation
• GitHub Issues