Content risk classification with pluggable backend adapters — part of the guardian-js toolkit.

Installation

pnpm add @guardian-js/core @guardian-js/content-classification zod

Usage

import { ContentClassificationService } from '@guardian-js/content-classification';
import { MyModerationAdapter } from './adapters/MyModerationAdapter';

const service = new ContentClassificationService(new MyModerationAdapter());

// Classify text
const textResult = await service.classify({
  type: 'text',
  content: 'Content submitted by the user...',
  locale: 'pt-BR'
});

// Classify a URL
const urlResult = await service.classify({
  type: 'url',
  url: 'https://example.com/some-page'
});

if (textResult.success) {
  const { riskLevel, categories, confidence } = textResult.data;
  // riskLevel: 'safe' | 'low' | 'medium' | 'high' | 'blocked'
  // categories: Array<'adult_content' | 'violence' | 'hate_speech' | 'gambling' | 'drugs' | 'self_harm' | 'safe'>
  // confidence: number (0–1)
}

Testing with the stub adapter

import { ContentClassificationService, StubContentClassificationAdapter } from '@guardian-js/content-classification';

// Returns 'safe' by default
const service = new ContentClassificationService(new StubContentClassificationAdapter());

// Override for high-risk scenarios
const highRiskService = new ContentClassificationService(
  new StubContentClassificationAdapter({ riskLevel: 'high', categories: ['adult_content'] })
);

Implementing your own adapter

import type { ContentClassificationProvider, ContentClassificationRequest, ContentClassificationResult, Result } from '@guardian-js/core';
import { ok, err, guardianError } from '@guardian-js/core';

export class MyModerationAdapter implements ContentClassificationProvider {
  public readonly name = 'my-moderation-api';

  public async classify(request: ContentClassificationRequest): Promise<Result<ContentClassificationResult>> {
    try {
      const input = request.type === 'text' ? request.content : request.url;
      const response = await myModerationApi.analyze(input);
      return ok({
        riskLevel: response.riskLevel,
        categories: response.categories,
        confidence: response.confidence,
        providerRef: response.id ?? null
      });
    } catch {
      return err(guardianError('PROVIDER_UNAVAILABLE', 'Moderation API unreachable'));
    }
  }
}

License

Apache 2.0