# BackPRO - Integracje API

## 1. OpenAI API (Generowanie artykułów)

### Endpoint
`POST https://api.openai.com/v1/chat/completions`

### Konfiguracja
- **Model:** konfigurowalny w ustawieniach (domyślnie `gpt-4o`)
- **Klucz API:** przechowywany w tabeli `settings`

### Struktura zapytania

```json
{
    "model": "gpt-4o",
    "messages": [
        {
            "role": "system",
            "content": "Jesteś doświadczonym copywriterem SEO. Pisz artykuły w języku polskim, optymalizowane pod SEO. Artykuł powinien mieć {min_words}-{max_words} słów, zawierać nagłówki H2 i H3, być angażujący i merytoryczny. Formatuj treść w HTML (bez tagów <html>, <body>, <head>). Zwróć odpowiedź w formacie JSON: {\"title\": \"tytuł\", \"content\": \"treść HTML\"}"
        },
        {
            "role": "user",
            "content": "Napisz artykuł na temat: {topic_name}\nWytyczne: {topic_description}\n\nWAŻNE - NIE pisz o następujących tematach, bo artykuły o nich już istnieją na stronie:\n{lista_istniejących_tytułów}"
        }
    ],
    "temperature": 0.8,
    "max_tokens": 4000,
    "response_format": { "type": "json_object" }
}
```

### Obsługa odpowiedzi
1. Parsowanie JSON z odpowiedzi
2. Walidacja - czy zawiera `title` i `content`
3. Sanityzacja HTML treści
4. Zapis do tabeli `articles`

### Obsługa błędów
- Rate limiting (429) → retry z exponential backoff
- Timeout → zapis status=failed z error_message
- Nieprawidłowy JSON → próba ekstrakcji treści z raw response

### Klasa: `OpenAIService`
```php
class OpenAIService {
    public function generateArticle(
        string $topicName,
        string $topicDescription,
        array $existingTitles
    ): array  // ['title' => '', 'content' => '']
}
```

---

## 2. WordPress REST API (Publikacja)

### Wymagania po stronie WordPressa
- WordPress 4.7+ (REST API wbudowane)
- Utworzony użytkownik z rolą **Author** lub **Editor**
- Wygenerowane **Application Password** (WP 5.6+: Użytkownicy → Profil → Application Passwords)

### Autentykacja
HTTP Basic Auth z Application Password:
```
Authorization: Basic base64(username:application_password)
```

### Używane endpointy

#### Test połączenia
```
GET {site_url}/wp-json/wp/v2/posts?per_page=1
```

#### Pobieranie kategorii
```
GET {site_url}/wp-json/wp/v2/categories?per_page=100
```

#### Upload obrazka (media)
```
POST {site_url}/wp-json/wp/v2/media
Content-Type: image/jpeg
Content-Disposition: attachment; filename="article-image.jpg"
Body: [binary image data]
```
Zwraca `id` mediów do użycia jako `featured_media`.

#### Tworzenie posta
```json
POST {site_url}/wp-json/wp/v2/posts
{
    "title": "Tytuł artykułu",
    "content": "<p>Treść HTML...</p>",
    "status": "publish",
    "categories": [15],
    "featured_media": 42
}
```

### Klasa: `WordPressService`
```php
class WordPressService {
    public function testConnection(Site $site): bool
    public function getCategories(Site $site): array
    public function uploadMedia(Site $site, string $imageData, string $filename): int
    public function createPost(
        Site $site,
        string $title,
        string $content,
        ?int $categoryId = null,
        ?int $mediaId = null
    ): int  // zwraca wp_post_id
}
```

---

## 3. Freepik API (Obrazki)

### AI Image Generation
`POST https://api.freepik.com/v1/ai/text-to-image`

```json
{
    "prompt": "Professional blog header image about {topic}: {article_title}",
    "negative_prompt": "text, watermark, logo",
    "image": {
        "size": "landscape_16_9"
    }
}
```

**Headers:**
```
x-freepik-api-key: {api_key}
Content-Type: application/json
```

### Alternatywy (fallback)

#### Unsplash API (darmowe stocki)
```
GET https://api.unsplash.com/search/photos?query={topic_keywords}&orientation=landscape
Authorization: Client-ID {access_key}
```

#### Pexels API (darmowe stocki)
```
GET https://api.pexels.com/v1/search?query={topic_keywords}&orientation=landscape&per_page=1
Authorization: {api_key}
```

### Klasa: `ImageService`
```php
class ImageService {
    public function generate(string $articleTitle, string $topicName): array
    // Zwraca ['data' => binary, 'filename' => 'image.jpg', 'mime' => 'image/jpeg']

    // Wewnętrznie wybiera provider na podstawie ustawienia 'image_provider':
    private function generateFreepik(string $prompt): array
    private function searchUnsplash(string $query): array
    private function searchPexels(string $query): array
}
```

---

## 4. Konfiguracja API w panelu

Ustawienia przechowywane w tabeli `settings`:

| Klucz | Opis | Przykład |
|-------|------|---------|
| openai_api_key | Klucz API OpenAI | sk-proj-... |
| openai_model | Model do artykułów | gpt-4o |
| freepik_api_key | Klucz API Freepik | fpk-... |
| unsplash_api_key | Klucz API Unsplash (opcjonalnie) | ... |
| pexels_api_key | Klucz API Pexels (opcjonalnie) | ... |
| image_provider | Aktywny provider obrazków | freepik / unsplash / pexels |
| article_min_words | Min. słów w artykule | 800 |
| article_max_words | Max. słów w artykule | 1200 |

## 5. Limity i koszty (orientacyjne)

| API | Limit | Koszt |
|-----|-------|-------|
| OpenAI GPT-4o | Brak limitu (pay-per-use) | ~$0.01-0.03 / artykuł |
| OpenAI GPT-4o-mini | Brak limitu | ~$0.001-0.003 / artykuł |
| Freepik AI | Zależy od planu | Od darmowego (ograniczony) |
| Unsplash | 50 req/h (demo) | Darmowe |
| Pexels | 200 req/h | Darmowe |
