← Zurück zur Suche
Coocle Logo

Coocle Dokumentation

Unabhängiges Open-Source-Projekt, nicht mit Google verbunden.

API-Endpunkte

Coocle bietet eine RESTful-API für Suche, Statistiken und Newsletter-Verwaltung.

Suche

GET /api/search

Parameter:

  • q (erforderlich) – Suchbegriff
  • limit (optional) – Maximale Ergebnisse (Standard: 10)
  • summarize (optional) – Zusammenfassung mit Ollama generieren (true/false)

Statistiken

GET /api/stats

Gibt die Anzahl der indexierten Seiten zurück.

GET /api/pages/overview

Detaillierte Übersicht über indexierte und in der Warteschlange befindliche Seiten.

GET /api/github/stats

GitHub-Repository-Statistiken (Stars, Forks, PRs). Erfordert GITHUB_REPO Konfiguration.

Newsletter

POST /api/newsletter/subscribe

Body:

{
  "email": "deine@email.de",
  "name": "Dein Name (optional)"
}
POST /api/newsletter/send

Sendet einen Newsletter an alle Abonnenten. Erfordert X-Admin-Token Header und SMTP-Konfiguration.

Body:

{
  "subject": "Newsletter-Betreff",
  "html": "
HTML-Inhalt
",
  "text": "Text-Inhalt"
}
POST /api/newsletter/check-milestones

Prüft auf Meilensteine (Seiten, Abonnenten, GitHub) und sendet automatisch Newsletter. Erfordert X-Admin-Token Header und SMTP-Konfiguration.

System

GET /api/healthz

Gesundheitscheck für Monitoring.

Newsletter-System

Coocle verfügt über ein vollständiges Newsletter-System mit SMTP-Versand und Meilenstein-benachrichtigungen.

Abonnenten verwalten

Abonnenten können sich über das Webformular oder die API anmelden. Die Daten werden lokal in SQLite gespeichert.

Newsletter senden

Newsletter werden direkt über SMTP versendet – keine externen Dienste erforderlich. Unterstützt HTML und Text-Inhalte.

Admin-Token

Das Admin-Token (COOCLE_NEWSLETTER_ADMIN_TOKEN) ist ein geheimes Passwort, das erforderlich ist, um geschützte Newsletter-Aktionen auszuführen:

  • /api/newsletter/send – Newsletter an alle Abonnenten senden
  • /api/newsletter/check-milestones – Meilensteine prüfen und Newsletter senden

Das Token muss als HTTP-Header gesendet werden:

X-Admin-Token: dein-geheimes-token

Wichtig: Das Token sollte sicher generiert (z.B. mit openssl rand -base64 32) und niemals öffentlich geteilt werden. Es wird als Umgebungsvariable konfiguriert:

COOCLE_NEWSLETTER_ADMIN_TOKEN=dein-geheimes-token-hier

Meilenstein-Newsletter

Das System erkennt automatisch Meilensteine und versendet gestaltete Newsletter:

  • Seiten: 100, 500, 1K, 2.5K, 5K, 10K, 25K, 50K, 100K indexierte Seiten
  • Abonnenten: 10, 25, 50, 100, 250, 500, 1K, 2.5K, 5K Abonnenten
  • GitHub Stars: 10, 25, 50, 100, 250, 500, 1K Stars
  • GitHub Forks: 5, 10, 25, 50, 100, 250, 500 Forks

Bereits gesendete Meilensteine werden in der Datenbank gespeichert und nicht wiederholt.

SMTP-Konfiguration

Für den Newsletter-Versand müssen folgende Umgebungsvariablen konfiguriert werden:

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=deine@email.de
SMTP_PASSWORD=dein-app-passwort
SMTP_USE_TLS=true
SMTP_SENDER_EMAIL=newsletter@example.com
SMTP_SENDER_NAME=Coocle

GitHub-Integration

Coocle kann GitHub-Repository-Statistiken abrufen und für Meilenstein-Newsletter verwenden.

GitHub-Stats API

Der Endpunkt /api/github/stats ruft folgende Daten ab:

  • Stars (Stargazers)
  • Forks
  • Offene Issues
  • Offene Pull Requests
  • Watcher

Konfiguration

GITHUB_REPO=r4k5O/coocle
GITHUB_API_TOKEN=ghp_xxxxxxxxxxxx (optional, für höhere Rate-Limits)

Meilenstein-Newsletter

Wenn GitHub-Stats konfiguriert sind, prüft /api/newsletter/check-milestones automatisch auf GitHub-Meilensteine und versendet gestaltete Newsletter mit Statistik-Karten.

Umgebungsvariablen

Coocle wird über Umgebungsvariablen konfiguriert. Siehe .env.example für alle Optionen.

Variable Beschreibung Standard
COOCLE_DB Pfad zur SQLite-Datenbank data/coocle.db
OLLAMA_HOST Ollama-Host für Zusammenfassungen http://localhost:11434
OLLAMA_CHAT_MODEL Ollama-Modell für Zusammenfassungen deepseek-r1:1.5b
SMTP_HOST SMTP-Server für Newsletter –
GITHUB_REPO GitHub-Repository (owner/repo) –
COOCLE_NEWSLETTER_ADMIN_TOKEN Admin-Token für Newsletter-Versand –

Rate-Limiting

COOCLE_API_RATE_LIMIT=60
COOCLE_API_RATE_WINDOW_S=60
COOCLE_SUMMARY_RATE_LIMIT=6
COOCLE_SUMMARY_RATE_WINDOW_S=60

Open Source

Coocle ist ein Open-Source-Projekt. Der Quellcode ist auf GitHub verfügbar:

https://github.com/r4k5O/coocle

Beiträge sind willkommen! Fork das Repository und erstelle einen Pull Request.