{"id":27779238,"url":"https://github.com/kynuxdev/small-swear-api","last_synced_at":"2026-02-21T23:03:16.548Z","repository":{"id":290273253,"uuid":"973882765","full_name":"KynuxDev/Small-Swear-Api","owner":"KynuxDev","description":"Türkçe metinlerde küfür ve argo kelimeleri algılayan, kategorize eden ve sansürleyen Node.js tabanlı RESTful API.","archived":false,"fork":false,"pushed_at":"2025-04-27T23:34:14.000Z","size":0,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-28T00:28:04.634Z","etag":null,"topics":["api","content-moderation","expressjs","kynuxdev","nlp","nodejs","profanity-filter","rest-api","small-swear-api","text-processing","turkish-swear-detection"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KynuxDev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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-27T23:33:32.000Z","updated_at":"2025-04-27T23:38:38.000Z","dependencies_parsed_at":"2025-04-28T00:28:43.364Z","dependency_job_id":null,"html_url":"https://github.com/KynuxDev/Small-Swear-Api","commit_stats":null,"previous_names":["kynuxdev/small-swear-api"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KynuxDev%2FSmall-Swear-Api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KynuxDev%2FSmall-Swear-Api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KynuxDev%2FSmall-Swear-Api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KynuxDev%2FSmall-Swear-Api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KynuxDev","download_url":"https://codeload.github.com/KynuxDev/Small-Swear-Api/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251676604,"owners_count":21626040,"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":["api","content-moderation","expressjs","kynuxdev","nlp","nodejs","profanity-filter","rest-api","small-swear-api","text-processing","turkish-swear-detection"],"created_at":"2025-04-30T09:30:09.093Z","updated_at":"2026-02-21T23:03:11.503Z","avatar_url":"https://github.com/KynuxDev.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Küfür Algılama API (Türkçe)\n\n[![Node.js CI](https://github.com/KynuxDev/Small-Swear-Api/actions/workflows/node.js.yml/badge.svg)](https://github.com/KynuxDev/Small-Swear-Api/actions/workflows/node.js.yml)\n\nBu proje, sağlanan metin içerisindeki Türkçe küfürleri ve argo kelimeleri algılamak, kategorize etmek ve isteğe bağlı olarak sansürlemek için geliştirilmiş, Node.js tabanlı bir RESTful API sunar.\n\n## ✨ Özellikler\n\n*   **Kapsamlı Küfür Algılama:** Genişletilebilir kelime listeleri kullanarak metinlerdeki küfürleri tespit eder.\n*   **Kelime Normalizasyon:** Farklı yazım şekillerini (büyük/küçük harf, Türkçe karakterler, leetspeak) normalize ederek algılama doğruluğunu artırır.\n*   **Hassasiyet Seviyeleri:** Algılama hassasiyetini ayarlama imkanı (`exact`, `normal`, `aggressive`).\n*   **Kelime İçi Arama:** Kelimelerin içinde geçen küfürleri de bulma seçeneği (`matchInside`).\n*   **Sansürleme:** Tespit edilen küfürleri `*` karakteri ile otomatik olarak sansürler.\n*   **Kategorizasyon:** Küfürleri yapılandırılabilir kategorilere ayırır (örneğin: \"hakaret\", \"argo\", \"cinsel içerik\").\n*   **Beyaz Liste:** Belirli kelimelerin yanlışlıkla küfür olarak algılanmasını engeller.\n*   **Yapılandırılabilirlik:** `config.json` dosyası üzerinden kolayca yapılandırılabilir (port, kelime listeleri, güvenlik ayarları vb.).\n*   **Güvenlik:** Temel güvenlik önlemleri (Helmet, Rate Limiting) içerir.\n\n## 🚀 Teknolojiler\n\n*   **Node.js:** Çalışma ortamı\n*   **Express.js:** Web framework'ü\n*   **Helmet:** HTTP başlıklarını ayarlayarak güvenliği artırır\n*   **express-rate-limit:** API isteklerini sınırlar\n\n## 🛠️ Kurulum ve Başlatma\n\n1.  **Projeyi Klonlayın:**\n    ```bash\n    git clone https://github.com/KynuxDev/Small-Swear-Api.git\n    cd Small-Swear-Api\n    ```\n2.  **Bağımlılıkları Yükleyin:**\n    ```bash\n    npm install\n    ```\n3.  **Yapılandırma Dosyasını Oluşturun/Düzenleyin:**\n    *   Proje ana dizininde `config.json` adında bir dosya oluşturun.\n    *   Aşağıdaki örnek yapıyı kullanarak kendi ayarlarınızı yapın:\n\n    ```json\n    {\n      \"server\": {\n        \"port\": 3000,\n        \"hostname\": \"localhost\" // İsteğe bağlı, boş bırakılırsa 'localhost' kullanılır\n      },\n      \"swearDetection\": {\n        \"useCategorizedList\": true, // true ise categorizedWordlistFile kullanılır, false ise simpleWordlistFile\n        \"simpleWordlistFile\": \"wordlist.txt\", // Basit küfür listesi dosya adı\n        \"categorizedWordlistFile\": \"categorized_wordlist.json\", // Kategorili küfür listesi dosya adı\n        \"whitelistFile\": \"whitelist.txt\" // Beyaz liste dosya adı\n      },\n      \"security\": {\n        \"rateLimit\": {\n          \"windowMs\": 15 * 60 * 1000, // 15 dakika\n          \"maxRequests\": 100 // 15 dakika içinde IP başına 100 istek\n        },\n        \"maxTextLength\": 5000 // Analiz edilecek maksimum metin karakter sayısı\n      }\n    }\n    ```\n4.  **Kelime Listelerini Hazırlayın:**\n    *   `config.json` içinde belirttiğiniz dosya adlarına göre (`wordlist.txt`, `categorized_wordlist.json`, `whitelist.txt`) kelime listelerinizi proje ana dizinine ekleyin. (Formatlar için \"Kelime Listeleri\" bölümüne bakın.)\n5.  **Uygulamayı Başlatın:**\n    *   **Normal Mod:**\n        ```bash\n        node index.js\n        ```\n    *   **Geliştirme Modu (nodemon ile otomatik yeniden başlatma için):**\n        Eğer `nodemon` kuruluysa ve `package.json` içinde bir `dev` script'i tanımlıysa (örneğin: `\"dev\": \"nodemon index.js\"`):\n        ```bash\n        npm run dev\n        ```\n\nAPI artık `http://\u003chostname\u003e:\u003cport\u003e` adresinde çalışıyor olacaktır (örneğin: `http://localhost:3000`).\n\n## 🔌 API Kullanımı\n\n### Endpoint: `GET /api/swear/detect`\n\nMetin içinde küfür algılar ve analiz sonuçlarını döndürür.\n\n**Query Parametreleri:**\n\n| Parametre     | Açıklama                                                                                                                                                              | Tür      | Gerekli Mi? | Varsayılan |\n| :------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | :---------- | :--------- |\n| `text`        | Analiz edilecek metin.                                                                                                                                                | `string` | **Evet**    | -          |\n| `censor`      | `true` veya `1` ise bulunan küfürler sansürlenir (`*` ile).                                                                                                            | `boolean`| Hayır       | `false`    |\n| `matchInside` | `true` veya `1` ise ve `sensitivity=normal` ise, kelimelerin *içinde* geçen küfürler de aranır. **Dikkat:** Yanlış pozitiflere neden olabilir.                          | `boolean`| Hayır       | `false`    |\n| `sensitivity` | Algılama hassasiyeti: \u003cbr\u003e - `exact`: Sadece tam kelime eşleşmesi (normalize edilmiş). `matchInside` yoksayılır. \u003cbr\u003e - `normal`: Tam kelime eşleşmesi + `matchInside` kontrolü. \u003cbr\u003e - `aggressive`: Tam kelime eşleşmesi + Her zaman kelime içi arama. `matchInside` yoksayılır. | `string` | Hayır       | `normal`   |\n\n**Örnek İstekler:**\n\n*   Basit algılama:\n    `/api/swear/detect?text=bu+çok+kötü+bir+durum`\n*   Sansürlü ve kelime içi arama (normal hassasiyet):\n    `/api/swear/detect?text=lanet+olsun+sana\u0026censor=true\u0026matchInside=true`\n*   Sansürlü ve agresif hassasiyet:\n    `/api/swear/detect?text=lanetolsun+sana\u0026censor=true\u0026sensitivity=aggressive`\n*   Sadece tam eşleşme (sansürsüz):\n    `/api/swear/detect?text=lanetolsun+sana\u0026sensitivity=exact`\n\n**Başarılı Yanıt (`200 OK`):**\n\nYanıt, sorgu detaylarını ve analiz sonuçlarını içerir.\n\n```json\n{\n    \"success\": true,\n    \"query\": {\n        \"text\": \"lanetolsun sana\", // Gönderilen orijinal metin\n        \"censor\": true,           // Sansürleme istendi mi?\n        \"match_inside_requested\": false, // matchInside istendi mi?\n        \"sensitivity\": \"aggressive\", // Kullanılan hassasiyet seviyesi\n        \"match_inside_effective\": true, // Kelime içi arama etkin miydi?\n        \"provided_length\": 15     // Gönderilen metnin uzunluğu\n    },\n    \"analysis\": {\n        \"contains_swear\": true,      // Küfür bulundu mu?\n        \"detected_swears\": [         // Bulunan küfürlerin detayları\n            {\n                \"word\": \"lanetolsun\", // Orijinal kelime\n                \"category\": \"kaba\",   // Kategorisi (eğer varsa)\n                \"reason\": \"içeriyor: lan\" // Bulunma nedeni (tam eşleşme veya içerdiği kelime)\n            }\n        ],\n        \"detected_swear_count\": 1,   // Toplam bulunan küfür sayısı\n        \"detected_categories\": [     // Bulunan tüm kategoriler (tekilleştirilmiş)\n            \"kaba\"\n        ],\n        \"category_counts\": {         // Her kategoriden kaç tane bulunduğu\n            \"kaba\": 1\n        },\n        \"word_count\": 2,             // Metindeki toplam kelime sayısı\n        \"swear_density\": 0.5000      // Küfür yoğunluğu (küfür sayısı / kelime sayısı)\n    },\n    \"censored_text\": \"********** sana\" // Eğer censor=true ise sansürlenmiş metin\n}\n```\n\n**Hata Yanıtları:**\n\n*   `400 Bad Request`: Eksik veya geçersiz parametre.\n    ```json\n    {\n        \"success\": false,\n        \"error\": \"Eksik zorunlu query parametresi: text\"\n    }\n    ```\n*   `413 Payload Too Large`: `text` parametresi `config.json`'daki `maxTextLength` sınırını aşıyor.\n    ```json\n    {\n        \"success\": false,\n        \"error\": \"Metin uzunluğu 5000 karakteri aşamaz.\"\n    }\n    ```\n*   `429 Too Many Requests`: Rate limit aşıldı.\n    ```json\n    {\n        \"success\": false,\n        \"error\": \"Çok fazla istek yapıldı, lütfen 15 dakika sonra tekrar deneyin.\"\n    }\n    ```\n*   `500 Internal Server Error`: Sunucu tarafında beklenmedik bir hata oluştu.\n    ```json\n    {\n        \"success\": false,\n        \"error\": \"Sunucuda beklenmeyen bir hata oluştu. Lütfen daha sonra tekrar deneyin.\"\n    }\n    ```\n\n## 📚 Kelime Listeleri Yönetimi\n\nAPI'nin etkinliği büyük ölçüde kullanılan kelime listelerine bağlıdır.\n\n*   **Normalizasyon:** Listelerdeki ve gelen metindeki kelimeler karşılaştırmadan önce `src/utils.js` içerisindeki `normalizeWord` fonksiyonu ile normalize edilir. Bu, büyük/küçük harf, Türkçe karakterler (ş-\u003es, ı-\u003ei vb.) ve bazı leetspeak karakterlerinin (örneğin: 3-\u003ee, @-\u003ea) tutarlı bir şekilde ele alınmasını sağlar. Liste hazırlarken bu normalizasyonun farkında olun.\n*   **Basit Liste (`wordlist.txt`):**\n    *   Her satıra bir küfür kelimesi yazılır.\n    *   Boş satırlar ve yorum satırları (örneğin `#` ile başlayanlar) genellikle göz ardı edilir (kod implementasyonuna bağlı).\n    *   Örnek:\n        ```\n        küfür1\n        argoKelime\n        hakaret\n        ```\n*   **Kategorili Liste (`categorized_wordlist.json`):**\n    *   JSON formatında bir nesnedir. Anahtarlar küfür kelimeleri, değerler ise kategorileridir.\n    *   Örnek:\n        ```json\n        {\n          \"küfür1\": \"hakaret\",\n          \"aptal\": \"aşağılama\",\n          \"lan\": \"argo\",\n          \"cinselistek\": \"cinsel\"\n        }\n        ```\n*   **Beyaz Liste (`whitelist.txt`):**\n    *   Basit liste formatındadır.\n    *   Buradaki kelimeler (normalize edilmiş halleriyle) küfür listesinde olsa bile asla küfür olarak algılanmaz. Özellikle `matchInside` kullanılırken yanlış pozitifleri önlemek için önemlidir.\n    *   Örnek:\n        ```\n        plan\n        aslan\n        cırtlak\n        ```\n*   **Liste Seçimi:** `config.json` dosyasındaki `useCategorizedList` ayarı `true` ise kategorili liste, `false` ise basit liste kullanılır. Kategorili liste kullanıldığında, kategorisiz basit küfür algılaması için de bu listenin anahtarları kullanılır.\n\n## 🛡️ Güvenlik\n\n*   **Helmet:** Yaygın web zafiyetlerine karşı koruma sağlamak için HTTP güvenlik başlıklarını ayarlar.\n*   **Rate Limiting:** API'nin kötüye kullanılmasını önlemek için belirli bir zaman aralığında yapılabilecek istek sayısını sınırlar (`config.json` -\u003e `security.rateLimit`).\n*   **Input Validation:** Gelen metin uzunluğu kontrol edilir (`config.json` -\u003e `security.maxTextLength`).\n\n## 🤝 Katkıda Bulunma\n\nKatkılarınız ve geri bildirimleriniz projeyi geliştirmek için çok değerlidir!\n\n*   **Hata Bildirimi:** Karşılaştığınız hataları lütfen GitHub Issues üzerinden detaylı olarak bildirin.\n*   **Özellik İsteği:** Yeni özellikler veya iyileştirmeler için GitHub Issues'u kullanabilirsiniz.\n*   **Kod Katkısı:**\n    1.  Projeyi fork edin.\n    2.  Yeni bir branch oluşturun (`git checkout -b yeni-ozellik`).\n    3.  Değişikliklerinizi yapın ve commit'leyin (`git commit -am 'Yeni özellik eklendi'`).\n    4.  Fork'unuza push edin (`git push origin yeni-ozellik`).\n    5.  Bir Pull Request oluşturun.\n\n## 📜 Lisans\n\nBu proje [MIT Lisansı](LICENSE) altında lisanslanmıştır.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkynuxdev%2Fsmall-swear-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkynuxdev%2Fsmall-swear-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkynuxdev%2Fsmall-swear-api/lists"}