{"id":28197499,"url":"https://github.com/utkarshthedev/filterx","last_synced_at":"2025-10-09T14:26:37.071Z","repository":{"id":288111952,"uuid":"966731488","full_name":"UtkarshTheDev/FilterX","owner":"UtkarshTheDev","description":null,"archived":false,"fork":false,"pushed_at":"2025-04-15T15:57:50.000Z","size":170,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-15T16:45:47.596Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://filter-x.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/UtkarshTheDev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-15T11:21:18.000Z","updated_at":"2025-04-15T15:57:54.000Z","dependencies_parsed_at":"2025-04-15T16:57:20.181Z","dependency_job_id":null,"html_url":"https://github.com/UtkarshTheDev/FilterX","commit_stats":null,"previous_names":["utkarshthedev/filterx"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UtkarshTheDev%2FFilterX","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UtkarshTheDev%2FFilterX/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UtkarshTheDev%2FFilterX/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UtkarshTheDev%2FFilterX/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/UtkarshTheDev","download_url":"https://codeload.github.com/UtkarshTheDev/FilterX/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254573600,"owners_count":22093732,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-16T17:14:35.789Z","updated_at":"2025-10-09T14:26:37.048Z","avatar_url":"https://github.com/UtkarshTheDev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🛡️ FilterX - Advanced Content Moderation API\n\n\u003e **Note from the Author**\n\u003e\n\u003e This was a **vibe-coding experiment** that exploded. The codebase is **fucked up** — tangled, fragile, and hostile.\n\u003e\n\u003e **No maintenance. No new features. No promises.**\n\u003e\n\u003e If you want to _fuck up_ your brain, try **contributing**, **refactoring**, or just using it.\n\u003e\n\u003e **Warning:** This project contains **thousands lines** of _vibe coded code_ in files. _Train your brain_ to get _fucked up_ daily just to _survive_ this.\n\u003e\n\u003e If you still insist, see the Quick Start below.\n\n**Enterprise-grade content filtering with AI-powered analysis and configurable security policies**\n\n[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg?style=flat-square)](https://github.com/UtkarshTheDev/FilterX)\n[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=flat-square\u0026logo=typescript\u0026logoColor=white)](https://www.typescriptlang.org/)\n[![Bun](https://img.shields.io/badge/Bun-000000?style=flat-square\u0026logo=bun\u0026logoColor=white)](https://bun.sh/)\n[![License](https://img.shields.io/badge/license-MIT-green.svg?style=flat-square)](LICENSE)\n\n---\n\n## Overview\n\nFilterX is a production-ready content moderation API that provides intelligent filtering of harmful content from text and images. Built for developers who need fast, reliable, and highly configurable content filtering with enterprise-grade performance.\n\n### How FilterX Works\n\n```mermaid\ngraph TD\n    A[Content] --\u003e B[FilterX]\n    B --\u003e C{Violations?}\n    C --\u003e|No| D[✅ Allow Content]\n    C --\u003e|Yes| E[❌ Block Content]\n```\n\n### Content Detection Capabilities\n\n- **Abusive Language** - Offensive content, harassment, and hate speech detection\n- **Personal Information** - Phone numbers, email addresses, and physical addresses\n- **Social Media Content** - Usernames, handles, and platform references\n- **Image Analysis** - AI-powered visual content moderation\n- **Context Awareness** - Conversation history analysis for improved accuracy\n\n### Key Features\n\n- ⚡ **High Performance** - Multi-tier caching with sub-100ms response times\n- 🔧 **Configurable** - Granular control over content filtering policies\n- 🤖 **AI-Powered** - Advanced machine learning models for nuanced detection\n- 🖼️ **Multi-Modal** - Process text, images, and mixed content\n- 📊 **Production Ready** - Built-in monitoring, analytics, and error handling\n- 🔒 **Secure by Default** - All filtering options default to restrictive settings\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- **[Bun](https://bun.sh/)** v1.0.0+ (Primary runtime)\n- **PostgreSQL** 13+ (Database)\n- **Redis** 6+ (Caching layer - optional but recommended)\n- **Node.js** 18+ (Alternative runtime)\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/UtkarshTheDev/FilterX.git\ncd FilterX\n\n# Install dependencies\nbun install\n\n# Configure environment\ncp .env.example .env\n# Edit .env with your database configuration\n\n# Initialize database\nbun run prepare-db\n\n# Start development server\nbun run dev\n\n# For production deployment\nbun start\n```\n\n### API Key Generation\n\n```bash\ncurl -X GET http://localhost:8000/v1/apikey\n```\n\n**Response:**\n\n```json\n{\n  \"key\": \"your-api-key\",\n  \"userId\": \"user_abc123\",\n  \"createdAt\": \"2025-01-15T10:30:00.000Z\"\n}\n```\n\n### Basic Usage Example\n\n```bash\ncurl -X POST http://localhost:8000/v1/filter \\\n  -H \"Authorization: Bearer your-api-key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"text\": \"Call me at 555-1234\"}'\n```\n\n**Response:**\n\n```json\n{\n  \"blocked\": true,\n  \"reason\": \"Contains phone number\",\n  \"flags\": [\"phone_number\"]\n}\n```\n\n---\n\n## API Documentation\n\n### Authentication\n\nAll API requests require authentication using your API key in the `Authorization` header:\n\n```bash\nAuthorization: Bearer your-api-key\n```\n\n### Available Endpoints\n\n| Endpoint           | Method | Description                                   |\n| ------------------ | ------ | --------------------------------------------- |\n| `/v1/filter`       | POST   | Main filtering endpoint for text and/or image |\n| `/v1/filter/text`  | POST   | Text-only content filtering                   |\n| `/v1/filter/image` | POST   | Image-only content filtering                  |\n| `/v1/filter/batch` | POST   | Batch processing for multiple items           |\n| `/v1/apikey`       | GET    | Generate or retrieve API key                  |\n| `/health`          | GET    | System health check                           |\n\n---\n\n## Configuration Options\n\nThe API uses a secure-by-default approach where all filtering options are disabled by default. You must explicitly enable specific content types through configuration flags.\n\n### Configuration Flow\n\n```mermaid\ngraph TD\n    A[Content Input] --\u003e B{Check Config}\n    B --\u003e C[allowPhone: false]\n    B --\u003e D[allowEmail: false]\n    B --\u003e E[allowAbuse: false]\n    C --\u003e F{Phone Detected?}\n    D --\u003e G{Email Detected?}\n    E --\u003e H{Abuse Detected?}\n    F --\u003e|Yes| I[❌ Block]\n    F --\u003e|No| J[✅ Allow]\n    G --\u003e|Yes| I\n    G --\u003e|No| J\n    H --\u003e|Yes| I\n    H --\u003e|No| J\n```\n\n### Default Behavior\n\n```json\n{\n  \"text\": \"Email me at john@test.com or call 555-1234\",\n  \"config\": {}\n}\n```\n\n**Result:** Content blocked (phone number and email detected)\n\n### Selective Permission\n\n```json\n{\n  \"text\": \"Email me at john@test.com\",\n  \"config\": {\n    \"allowEmail\": true\n  }\n}\n```\n\n**Result:** Content allowed (email permitted by configuration)\n\n### Configuration Parameters\n\n| Parameter                  | Description                            | Default |\n| -------------------------- | -------------------------------------- | ------- |\n| `allowAbuse`               | Allow abusive/offensive language       | `false` |\n| `allowPhone`               | Allow phone numbers                    | `false` |\n| `allowEmail`               | Allow email addresses                  | `false` |\n| `allowPhysicalInformation` | Allow physical addresses and locations | `false` |\n| `allowSocialInformation`   | Allow social media handles             | `false` |\n| `returnFilteredMessage`    | Return censored version of content     | `false` |\n| `analyzeImages`            | Enable AI-powered image analysis       | `false` |\n\n## Usage Examples\n\n### Restrictive Content Policy\n\nSuitable for family-friendly applications requiring strict content moderation:\n\n```bash\ncurl -X POST http://localhost:8000/v1/filter \\\n  -H \"Authorization: Bearer your-api-key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"text\": \"Hey, call me at 555-1234 or email john@test.com\",\n    \"config\": {\n      \"allowAbuse\": false,\n      \"allowPhone\": false,\n      \"allowEmail\": false,\n      \"returnFilteredMessage\": true\n    }\n  }'\n```\n\n**Response:**\n\n```json\n{\n  \"blocked\": true,\n  \"flags\": [\"phone_number\", \"email_address\"],\n  \"reason\": \"Contains phone number and email address\",\n  \"filteredMessage\": \"Hey, call me at [PHONE_REDACTED] or email [EMAIL_REDACTED]\"\n}\n```\n\n### Business Communication Platform\n\nConfiguration allowing professional contact information sharing:\n\n```bash\ncurl -X POST http://localhost:8000/v1/filter \\\n  -H \"Authorization: Bearer your-api-key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"text\": \"Contact me at john@company.com for business inquiries\",\n    \"config\": {\n      \"allowEmail\": true,\n      \"allowPhone\": true,\n      \"allowAbuse\": false\n    }\n  }'\n```\n\n**Response:**\n\n```json\n{\n  \"blocked\": false,\n  \"flags\": [],\n  \"reason\": \"Content passed all moderation checks\"\n}\n```\n\n### Social Platform with Abuse Prevention\n\nAllowing social media handles while blocking offensive content:\n\n```bash\ncurl -X POST http://localhost:8000/v1/filter \\\n  -H \"Authorization: Bearer your-api-key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"text\": \"Follow me @username, this content is inappropriate!\",\n    \"config\": {\n      \"allowSocialInformation\": true,\n      \"allowAbuse\": false,\n      \"returnFilteredMessage\": true\n    }\n  }'\n```\n\n**Response:**\n\n```json\n{\n  \"blocked\": true,\n  \"flags\": [\"abusive_language\"],\n  \"reason\": \"Contains offensive language\",\n  \"filteredMessage\": \"Follow me @username, this content is [CONTENT_FILTERED]!\"\n}\n```\n\n### Multi-Modal Content Analysis\n\nProcessing both text and image content:\n\n```bash\ncurl -X POST http://localhost:8000/v1/filter \\\n  -H \"Authorization: Bearer your-api-key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"text\": \"Check out this image\",\n    \"image\": \"data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...\",\n    \"config\": {\n      \"analyzeImages\": true\n    }\n  }'\n```\n\n### Batch Processing\n\nEfficient processing of multiple content items:\n\n```bash\ncurl -X POST http://localhost:8000/v1/filter/batch \\\n  -H \"Authorization: Bearer your-api-key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"items\": [\n      {\n        \"text\": \"First message to moderate\",\n        \"config\": {\"allowPhone\": false}\n      },\n      {\n        \"text\": \"Contact: admin@example.com\",\n        \"config\": {\"allowEmail\": true}\n      }\n    ]\n  }'\n```\n\n---\n\n## Response Format\n\nAll API endpoints return standardized JSON responses with consistent structure.\n\n### Response Flow\n\n```mermaid\ngraph LR\n    A[API Request] --\u003e B{Content Analysis}\n    B --\u003e|Clean| C[blocked: false]\n    B --\u003e|Violation| D[blocked: true]\n    C --\u003e E[flags: []]\n    D --\u003e F[flags: ['phone_number']]\n    E --\u003e G[Response JSON]\n    F --\u003e G\n    D --\u003e H[filteredMessage]\n    H --\u003e G\n```\n\n### Successful Response (Content Allowed)\n\n```json\n{\n  \"blocked\": false,\n  \"flags\": [],\n  \"reason\": \"Content passed all moderation checks\"\n}\n```\n\n### Blocked Content Response\n\n```json\n{\n  \"blocked\": true,\n  \"flags\": [\"phone_number\", \"email_address\"],\n  \"reason\": \"Contains phone number and email address\",\n  \"filteredMessage\": \"Contact me at [PHONE_REDACTED] or email [EMAIL_REDACTED]\"\n}\n```\n\n### Response Fields\n\n| Field             | Type       | Description                                                                   |\n| ----------------- | ---------- | ----------------------------------------------------------------------------- |\n| `blocked`         | `boolean`  | Indicates whether content was blocked (`true`) or allowed (`false`)           |\n| `flags`           | `string[]` | Array of detected content types (e.g., `[\"phone_number\", \"email_address\"]`)   |\n| `reason`          | `string`   | Human-readable explanation of the moderation decision                         |\n| `filteredMessage` | `string`   | Censored version of content (only present when `returnFilteredMessage: true`) |\n\n---\n\n## Troubleshooting\n\n### Authentication Errors\n\n**Issue:** \"Invalid API key\" or \"Unauthorized\" responses\n\n**Solution:**\n\n```bash\n# Ensure you're using GET method to obtain API key\ncurl -X GET http://localhost:8000/v1/apikey\n\n# Verify correct header format\ncurl -H \"Authorization: Bearer sk-your-actual-api-key\" ...\n```\n\n### Connection Issues\n\n**Issue:** \"Connection refused\" or network errors\n\n**Solution:**\n\n```bash\n# Verify server is running\nbun run dev\n\n# Test server health\ncurl http://localhost:8000/health\n```\n\n### Server Startup Issues\n\n**Issue:** Server fails to start or database connection errors\n\n**Solution:**\n\n```bash\n# Verify environment configuration\ncat .env\n\n# Reinitialize database\nbun run prepare-db\n\n# Check database connectivity\nbun run check:ts\n```\n\n---\n\n## Advanced Features\n\n### Context-Aware Analysis\n\nInclude conversation history for improved content understanding:\n\n```json\n{\n  \"text\": \"Yes, let's meet there\",\n  \"oldMessages\": [\n    \"Want to grab coffee?\",\n    \"Sure! How about Starbucks on Main St?\"\n  ],\n  \"config\": {\n    \"allowPhysicalInformation\": false\n  }\n}\n```\n\n### AI Model Selection\n\nConfigure processing speed and accuracy trade-offs:\n\n```json\n{\n  \"text\": \"Content to analyze\",\n  \"model\": \"normal\"\n}\n```\n\n### Model Performance Comparison\n\n```mermaid\ngraph TD\n    A[Content Input] --\u003e B{Model Selection}\n    B --\u003e|fast| C[⚡ Fast Model]\n    B --\u003e|normal| D[⚖️ Normal Model]\n    B --\u003e|pro| E[🎯 Pro Model]\n    C --\u003e F[~50ms Response]\n    D --\u003e G[~150ms Response]\n    E --\u003e H[~300ms Response]\n    F --\u003e I[85% Accuracy]\n    G --\u003e J[95% Accuracy]\n    H --\u003e K[99% Accuracy]\n```\n\n**Available Models:**\n\n- `fast` - Optimized for speed with basic accuracy (~50ms, 85% accuracy)\n- `normal` - Balanced performance and accuracy (~150ms, 95% accuracy, default)\n- `pro` - Maximum accuracy with longer processing time (~300ms, 99% accuracy)\n\n### System Health Monitoring\n\n```bash\ncurl http://localhost:8000/health\n```\n\n**Response:**\n\n```json\n{\n  \"status\": \"healthy\",\n  \"version\": \"1.0.0\",\n  \"uptime\": 86400,\n  \"database\": \"connected\",\n  \"redis\": \"connected\"\n}\n```\n\n---\n\n## Development\n\n### Testing\n\n```bash\n# Run test suite\nbun test\n\n# Run with coverage\nbun test --coverage\n```\n\n### Code Quality\n\n```bash\n# Lint codebase\nbun run lint\n\n# Format code\nbun run format\n\n# Type checking\nbun run check:ts\n```\n\n### Database Management\n\n```bash\n# Initialize database and tables\nbun run prepare-db\n\n# Test database connectivity\nbun run dev\n```\n\n---\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Built by [Utkarsh Tiwari](https://github.com/UtkarshTheDev)**\n\n[![GitHub stars](https://img.shields.io/github/stars/UtkarshTheDev/FilterX?style=social)](https://github.com/UtkarshTheDev/FilterX)\n[![Twitter Follow](https://img.shields.io/twitter/follow/UtkarshTheDev?style=social)](https://twitter.com/UtkarshTheDev)\n\n_Enterprise-grade content moderation powered by TypeScript and [Bun](https://bun.sh)_\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Futkarshthedev%2Ffilterx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Futkarshthedev%2Ffilterx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Futkarshthedev%2Ffilterx/lists"}