@sharpapi/sharpapi-node-detect-profanities 1.0.0

package/README.md

@@ -0,0 +1,427 @@
+![SharpAPI GitHub cover](https://sharpapi.com/sharpapi-github-php-bg.jpg "SharpAPI Node.js Client")
+
+# Profanity Detection API for Node.js
+
+## 🛡️ Detect profanities and inappropriate content with AI — powered by SharpAPI.
+
+[![npm version](https://img.shields.io/npm/v/@sharpapi/sharpapi-node-detect-profanities.svg)](https://www.npmjs.com/package/@sharpapi/sharpapi-node-detect-profanities)
+[![License](https://img.shields.io/npm/l/@sharpapi/sharpapi-node-detect-profanities.svg)](https://github.com/sharpapi/sharpapi-node-client/blob/master/LICENSE.md)
+
+**SharpAPI Profanity Detection** analyzes text content for profanities, offensive language, and inappropriate content using AI. Essential for content moderation, community guidelines enforcement, and maintaining safe user environments.
+
+---
+
+## 📋 Table of Contents
+
+1. [Requirements](#requirements)
+2. [Installation](#installation)
+3. [Usage](#usage)
+4. [API Documentation](#api-documentation)
+5. [Response Format](#response-format)
+6. [Examples](#examples)
+7. [License](#license)
+
+---
+
+## Requirements
+
+- Node.js >= 16.x
+- npm or yarn
+
+---
+
+## Installation
+
+### Step 1. Install the package via npm:
+
+```bash
+npm install @sharpapi/sharpapi-node-detect-profanities
+```
+
+### Step 2. Get your API key
+
+Visit [SharpAPI.com](https://sharpapi.com/) to get your API key.
+
+---
+
+## Usage
+
+```javascript
+const { SharpApiDetectProfanitiesService } = require('@sharpapi/sharpapi-node-detect-profanities');
+
+const apiKey = process.env.SHARP_API_KEY;
+const service = new SharpApiDetectProfanitiesService(apiKey);
+
+const userComment = `
+This is a sample comment that might contain inappropriate language.
+Checking for profanities and offensive content.
+`;
+
+async function checkContent() {
+  try {
+    const statusUrl = await service.detectProfanities(userComment);
+    console.log('Job submitted. Status URL:', statusUrl);
+
+    const result = await service.fetchResults(statusUrl);
+    const detection = result.getResultJson();
+
+    if (!detection.result.pass) {
+      console.log('⚠️ Profanity detected!');
+      console.log('Confidence:', detection.result.score + '%');
+      console.log('Reason:', detection.result.reason);
+    } else {
+      console.log('✅ Content is clean');
+    }
+  } catch (error) {
+    console.error('Error:', error.message);
+  }
+}
+
+checkContent();
+```
+
+---
+
+## API Documentation
+
+### Methods
+
+#### `detectProfanities(text: string): Promise<string>`
+
+Analyzes text content for profanities and inappropriate language.
+
+**Parameters:**
+- `text` (string, required): The text content to analyze
+
+**Returns:**
+- Promise<string>: Status URL for polling the job result
+
+---
+
+## Response Format
+
+The API returns a detection result with confidence score:
+
+```json
+{
+  "data": {
+    "type": "api_job_result",
+    "id": "a8f2c1b5-9e4d-4a3b-8c7f-6d5e4f3a2b1c",
+    "attributes": {
+      "status": "success",
+      "type": "content_detect_profanities",
+      "result": {
+        "pass": false,
+        "score": 92,
+        "reason": "The text contains explicit profanity and offensive language that violates community guidelines."
+      }
+    }
+  }
+}
+```
+
+**Result Fields:**
+- `pass` (boolean): `true` if content is clean, `false` if profanities detected
+- `score` (integer, 0-100): Confidence score of the detection
+  - `90-100`: Very high confidence
+  - `75-89`: High confidence
+  - `60-74`: Moderate confidence
+  - `Below 60`: Low confidence (may need human review)
+- `reason` (string): Explanation of why content was flagged or cleared
+
+---
+
+## Examples
+
+### Basic Profanity Detection
+
+```javascript
+const { SharpApiDetectProfanitiesService } = require('@sharpapi/sharpapi-node-detect-profanities');
+
+const service = new SharpApiDetectProfanitiesService(process.env.SHARP_API_KEY);
+
+const content = 'This is a sample user comment to check for inappropriate content.';
+
+service.detectProfanities(content)
+  .then(statusUrl => service.fetchResults(statusUrl))
+  .then(result => {
+    const detection = result.getResultJson().result;
+
+    if (detection.pass) {
+      console.log('✅ Content approved');
+    } else {
+      console.log(`⚠️ Content flagged (${detection.score}% confidence)`);
+      console.log(`Reason: ${detection.reason}`);
+    }
+  })
+  .catch(error => console.error('Detection failed:', error));
+```
+
+### Batch Content Moderation
+
+```javascript
+const service = new SharpApiDetectProfanitiesService(process.env.SHARP_API_KEY);
+
+const userComments = [
+  { id: 1, text: 'Great product! Really helpful.' },
+  { id: 2, text: 'Terrible service, very disappointed.' },
+  { id: 3, text: 'Amazing quality, highly recommend!' }
+];
+
+async function moderateComments(comments) {
+  const moderated = await Promise.all(
+    comments.map(async (comment) => {
+      try {
+        const statusUrl = await service.detectProfanities(comment.text);
+        const result = await service.fetchResults(statusUrl);
+        const detection = result.getResultJson().result;
+
+        return {
+          ...comment,
+          approved: detection.pass,
+          confidence: detection.score,
+          reason: detection.reason,
+          requiresReview: !detection.pass && detection.score < 75
+        };
+      } catch (error) {
+        return {
+          ...comment,
+          approved: false,
+          error: error.message,
+          requiresReview: true
+        };
+      }
+    })
+  );
+
+  return moderated;
+}
+
+const results = await moderateComments(userComments);
+
+const approved = results.filter(r => r.approved).length;
+const flagged = results.filter(r => !r.approved).length;
+const needsReview = results.filter(r => r.requiresReview).length;
+
+console.log(`📊 Moderation Summary:`);
+console.log(`Total: ${results.length}`);
+console.log(`✅ Approved: ${approved}`);
+console.log(`⚠️ Flagged: ${flagged}`);
+console.log(`👤 Needs Human Review: ${needsReview}`);
+```
+
+### Real-time Comment Filtering
+
+```javascript
+const service = new SharpApiDetectProfanitiesService(process.env.SHARP_API_KEY);
+
+async function filterComment(comment, autoReject = true) {
+  const statusUrl = await service.detectProfanities(comment.text);
+  const result = await service.fetchResults(statusUrl);
+  const detection = result.getResultJson().result;
+
+  const action = {
+    commentId: comment.id,
+    userId: comment.userId,
+    text: comment.text,
+    pass: detection.pass,
+    confidence: detection.score,
+    reason: detection.reason,
+    status: '',
+    action: ''
+  };
+
+  if (detection.pass) {
+    action.status = 'approved';
+    action.action = 'publish';
+  } else if (detection.score >= 85 && autoReject) {
+    action.status = 'rejected';
+    action.action = 'auto_reject';
+  } else if (detection.score >= 60) {
+    action.status = 'flagged';
+    action.action = 'hold_for_review';
+  } else {
+    action.status = 'uncertain';
+    action.action = 'manual_review';
+  }
+
+  return action;
+}
+
+const newComment = {
+  id: 'CMT-12345',
+  userId: 'USER-789',
+  text: 'What a fantastic experience! Absolutely loved it!'
+};
+
+const moderation = await filterComment(newComment);
+
+console.log(`Comment Status: ${moderation.status}`);
+console.log(`Action: ${moderation.action}`);
+console.log(`Confidence: ${moderation.confidence}%`);
+
+if (moderation.action === 'publish') {
+  console.log('✅ Comment published successfully');
+} else if (moderation.action === 'auto_reject') {
+  console.log('🚫 Comment automatically rejected');
+  console.log(`Reason: ${moderation.reason}`);
+} else {
+  console.log('⏸️ Comment held for manual review');
+}
+```
+
+### Forum Moderation Dashboard
+
+```javascript
+const service = new SharpApiDetectProfanitiesService(process.env.SHARP_API_KEY);
+
+async function generateModerationReport(posts) {
+  const analyzed = await Promise.all(
+    posts.map(async (post) => {
+      const statusUrl = await service.detectProfanities(post.content);
+      const result = await service.fetchResults(statusUrl);
+      const detection = result.getResultJson().result;
+
+      return {
+        postId: post.id,
+        author: post.author,
+        timestamp: post.timestamp,
+        pass: detection.pass,
+        score: detection.score,
+        reason: detection.reason,
+        severity: detection.score >= 90 ? 'high' :
+                 detection.score >= 75 ? 'medium' :
+                 detection.score >= 60 ? 'low' : 'uncertain'
+      };
+    })
+  );
+
+  const report = {
+    totalPosts: posts.length,
+    clean: analyzed.filter(a => a.pass).length,
+    flagged: analyzed.filter(a => !a.pass).length,
+    highSeverity: analyzed.filter(a => a.severity === 'high').length,
+    mediumSeverity: analyzed.filter(a => a.severity === 'medium').length,
+    lowSeverity: analyzed.filter(a => a.severity === 'low').length,
+    needsReview: analyzed.filter(a => a.severity === 'uncertain').length,
+    posts: analyzed.filter(a => !a.pass).map(a => ({
+      postId: a.postId,
+      author: a.author,
+      severity: a.severity,
+      score: a.score,
+      reason: a.reason
+    }))
+  };
+
+  return report;
+}
+
+const forumPosts = [
+  { id: 'POST-1', author: 'user123', content: 'Great discussion!', timestamp: new Date() },
+  { id: 'POST-2', author: 'user456', content: 'Thanks for sharing!', timestamp: new Date() },
+  { id: 'POST-3', author: 'user789', content: 'Very helpful post.', timestamp: new Date() }
+];
+
+const report = await generateModerationReport(forumPosts);
+
+console.log('📋 Moderation Report:');
+console.log(`Total Posts: ${report.totalPosts}`);
+console.log(`Clean: ${report.clean}`);
+console.log(`Flagged: ${report.flagged}`);
+console.log(`  - High Severity: ${report.highSeverity}`);
+console.log(`  - Medium Severity: ${report.mediumSeverity}`);
+console.log(`  - Low Severity: ${report.lowSeverity}`);
+console.log(`  - Needs Review: ${report.needsReview}`);
+
+if (report.posts.length > 0) {
+  console.log('\n🚨 Flagged Posts:');
+  report.posts.forEach(p => {
+    console.log(`  - ${p.postId} by ${p.author} (${p.severity} severity, ${p.score}%)`);
+    console.log(`    Reason: ${p.reason}`);
+  });
+}
+```
+
+---
+
+## Use Cases
+
+- **Social Media Platforms**: Moderate user comments and posts
+- **Community Forums**: Enforce community guidelines automatically
+- **Gaming Platforms**: Filter chat messages and usernames
+- **E-commerce**: Screen product reviews and seller messages
+- **Educational Platforms**: Maintain safe learning environments
+- **Dating Apps**: Screen user profiles and messages
+- **Customer Support**: Filter support tickets and feedback
+- **Live Chat**: Real-time message filtering
+
+---
+
+## Detection Capabilities
+
+The AI analyzes content for:
+
+- **Explicit Profanity**: Curse words and vulgar language
+- **Offensive Slurs**: Discriminatory or hate speech
+- **Sexual Content**: Inappropriate sexual references
+- **Harassment**: Threatening or bullying language
+- **Toxic Behavior**: Generally harmful or abusive content
+- **Masked Profanity**: Attempts to bypass filters with symbols or misspellings
+
+---
+
+## Integration Tips
+
+### Confidence Thresholds
+
+Recommended confidence score thresholds:
+
+- **≥ 90%**: Auto-reject/block (very high confidence)
+- **75-89%**: Flag for priority review (high confidence)
+- **60-74%**: Queue for review (moderate confidence)
+- **< 60%**: Manual review required (low confidence)
+
+### Performance Optimization
+
+- Use batch processing for bulk moderation
+- Cache results for repeated content checks
+- Implement queue systems for high-volume scenarios
+- Combine with other moderation tools for comprehensive coverage
+
+---
+
+## API Endpoint
+
+**POST** `/content/detect_profanities`
+
+For detailed API specifications, refer to:
+- [Main API Documentation](https://documenter.getpostman.com/view/31106842/2s9Ye8faUp)
+- [SharpAPI.com](https://sharpapi.com/)
+
+---
+
+## Related Packages
+
+- [@sharpapi/sharpapi-node-detect-spam](https://www.npmjs.com/package/@sharpapi/sharpapi-node-detect-spam) - Spam detection
+- [@sharpapi/sharpapi-node-detect-phones](https://www.npmjs.com/package/@sharpapi/sharpapi-node-detect-phones) - Phone number extraction
+- [@sharpapi/sharpapi-node-detect-emails](https://www.npmjs.com/package/@sharpapi/sharpapi-node-detect-emails) - Email extraction
+- [@sharpapi/sharpapi-node-detect-urls](https://www.npmjs.com/package/@sharpapi/sharpapi-node-detect-urls) - URL extraction
+- [@sharpapi/sharpapi-node-client](https://www.npmjs.com/package/@sharpapi/sharpapi-node-client) - Full SharpAPI SDK
+
+---
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE.md](LICENSE.md) file for details.
+
+---
+
+## Support
+
+- **Documentation**: [SharpAPI.com Documentation](https://sharpapi.com/documentation)
+- **Issues**: [GitHub Issues](https://github.com/sharpapi/sharpapi-node-client/issues)
+- **Email**: contact@sharpapi.com
+
+---
+
+**Powered by [SharpAPI](https://sharpapi.com/) - AI-Powered API Workflow Automation**

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@sharpapi/sharpapi-node-detect-profanities",
+  "version": "1.0.0",
+  "description": "SharpAPI.com Node.js SDK for detecting profanities in text",
+  "main": "src/index.js",
+  "scripts": {
+    "test": "jest"
+  },
+  "keywords": [
+    "sharpapi",
+    "ai-powered",
+    "ai capabilities",
+    "api",
+    "ai api",
+    "api integration",
+    "artificial intelligence",
+    "natural language processing",
+    "restful api",
+    "nodejs",
+    "software development",
+    "content analysis",
+    "content moderation",
+    "profanity detection",
+    "text processing"
+  ],
+  "author": "Dawid Makowski <contact@sharpapi.com>",
+  "license": "MIT",
+  "dependencies": {
+    "@sharpapi/sharpapi-node-core": "file:../sharpapi-node-core"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sharpapi/sharpapi-node-detect-profanities.git"
+  }
+}

package/src/SharpApiDetectProfanitiesService.js

@@ -0,0 +1,22 @@
+const { SharpApiCoreService, SharpApiJobTypeEnum } = require('@sharpapi/sharpapi-node-core');
+
+/**
+ * Service for detecting profanities in text using SharpAPI.com
+ */
+class SharpApiDetectProfanitiesService extends SharpApiCoreService {
+  /**
+   * Analyzes the provided text for any profanities or inappropriate language.
+   * Useful for content moderation, user-generated content validation, and
+   * maintaining community guidelines.
+   *
+   * @param {string} text
+   * @returns {Promise<string>} - The status URL.
+   */
+  async detectProfanities(text) {
+    const data = { content: text };
+    const response = await this.makeRequest('POST', SharpApiJobTypeEnum.CONTENT_DETECT_PROFANITIES.url, data);
+    return this.parseStatusUrl(response);
+  }
+}
+
+module.exports = { SharpApiDetectProfanitiesService };

package/src/index.js

@@ -0,0 +1,6 @@
+// sharpapi-node-detect-profanities/src/index.js
+const { SharpApiDetectProfanitiesService } = require('./SharpApiDetectProfanitiesService');
+
+module.exports = {
+  SharpApiDetectProfanitiesService,
+};