---
phase: 88-allegro-user-agent
plan: 01
type: execute
wave: 1
depends_on: []
files_modified: [src/Modules/Settings/AllegroApiClient.php, src/Modules/Settings/AllegroOAuthClient.php, src/Modules/Shipments/AllegroTrackingService.php, .env.example, config/app.php]
autonomous: true
delegation: off
---

<objective>
## Goal
Dodanie nagłówka User-Agent do wszystkich requestów HTTP wysyłanych do Allegro REST API, zgodnie z wymaganiami art. 3.4.c Regulaminu REST API Allegro.

## Purpose
Od 1 lipca 2026 Allegro będzie odrzucać requesty bez poprawnego User-Agent. Bez tej zmiany integracja z Allegro przestanie działać.

## Output
Wszystkie requesty do Allegro API (REST, OAuth, tracking) będą zawierać nagłówek:
`orderPRO/1.0.0 (+https://orderpro.pl/info)`
</objective>

<context>
## Project Context
@.paul/PROJECT.md
@.paul/ROADMAP.md
@.paul/STATE.md

## Source Files
@src/Modules/Settings/AllegroApiClient.php — główny klient REST API (4 metody z CURLOPT_HTTPHEADER: linie 216, 281, 345, 393)
@src/Modules/Settings/AllegroOAuthClient.php — klient OAuth token exchange (1 metoda: linia 153)
@src/Modules/Shipments/AllegroTrackingService.php — tracking przesyłek (2 metody: linie 136, 186)
@.env.example — konfiguracja aplikacji (APP_NAME=orderPRO)
</context>

<acceptance_criteria>

## AC-1: User-Agent w requestach REST API
```gherkin
Given AllegroApiClient wysyła request do Allegro API (GET, POST, PUT, POST binary)
When request jest wykonywany przez dowolną metodę (requestJson, postJson, putJson, postBinary)
Then nagłówek User-Agent jest obecny w formacie "orderPRO/1.0.0 (+https://orderpro.pl/info)"
```

## AC-2: User-Agent w requestach OAuth
```gherkin
Given AllegroOAuthClient wymienia authorization code lub odświeża token
When request OAuth jest wykonywany przez requestToken()
Then nagłówek User-Agent jest obecny w tym samym formacie
```

## AC-3: User-Agent w requestach tracking
```gherkin
Given AllegroTrackingService odpytuje API o status przesyłki
When request jest wykonywany przez edgeApiRequest() lub apiRequest()
Then nagłówek User-Agent jest obecny w tym samym formacie
```

## AC-4: Konfigurowalność User-Agent
```gherkin
Given administrator chce zmienić URL dokumentacji lub wersję w User-Agent
When zmieni wartości ALLEGRO_USER_AGENT_URL i APP_VERSION w .env
Then wszystkie requesty używają zaktualizowanych wartości
```

</acceptance_criteria>

<tasks>

<task type="auto">
  <name>Task 1: Dodanie stałej User-Agent i konfiguracji</name>
  <files>.env.example, config/app.php</files>
  <action>
    1. W `.env.example` dodać zmienne:
       - `APP_VERSION=1.0.0`
       - `ALLEGRO_USER_AGENT_URL=https://orderpro.pl/info`
    2. W `config/app.php` (lub tam gdzie jest odczyt konfiguracji) upewnić się że te zmienne są dostępne.
    3. Analogicznie w `.env` (produkcyjne wartości).
    
    Format User-Agent: `{APP_NAME}/{APP_VERSION} (+{ALLEGRO_USER_AGENT_URL})`
    Przykład: `orderPRO/1.0.0 (+https://orderpro.pl/info)`
  </action>
  <verify>Grep .env.example powinien zawierać APP_VERSION i ALLEGRO_USER_AGENT_URL</verify>
  <done>AC-4 satisfied: zmienne konfiguracyjne zdefiniowane</done>
</task>

<task type="auto">
  <name>Task 2: Dodanie User-Agent do AllegroApiClient</name>
  <files>src/Modules/Settings/AllegroApiClient.php</files>
  <action>
    1. Dodać prywatną metodę `buildUserAgent(): string` która buduje string User-Agent z ENV:
       - `getenv('APP_NAME') ?: 'orderPRO'`
       - `getenv('APP_VERSION') ?: '1.0.0'`
       - `getenv('ALLEGRO_USER_AGENT_URL') ?: 'https://orderpro.pl/info'`
       - Zwraca: `"{name}/{version} (+{url})"`
    2. Dodać `'User-Agent: ' . $this->buildUserAgent()` do CURLOPT_HTTPHEADER w 4 metodach:
       - `postJson()` (linia ~216)
       - `putJson()` (linia ~281)
       - `postBinary()` (linia ~345)
       - `requestJson()` (linia ~393)
    
    Avoid: nie duplikować logiki budowania stringa — jedna metoda, 4 wywołania.
  </action>
  <verify>Grep AllegroApiClient.php za "User-Agent" — powinno być 4 wystąpienia w HTTPHEADER + 1 metoda buildUserAgent</verify>
  <done>AC-1 satisfied: wszystkie 4 metody REST API wysyłają User-Agent</done>
</task>

<task type="auto">
  <name>Task 3: Dodanie User-Agent do AllegroOAuthClient i AllegroTrackingService</name>
  <files>src/Modules/Settings/AllegroOAuthClient.php, src/Modules/Shipments/AllegroTrackingService.php</files>
  <action>
    1. W `AllegroOAuthClient.php`:
       - Dodać analogiczną metodę `buildUserAgent(): string` (lub wydzielić do traita/helpera jeśli nie nadmiarowe)
       - Dodać `'User-Agent: ' . $this->buildUserAgent()` do CURLOPT_HTTPHEADER w `requestToken()` (linia ~153)
    
    2. W `AllegroTrackingService.php`:
       - Dodać analogiczną metodę `buildUserAgent(): string`
       - Dodać `'User-Agent: ' . $this->buildUserAgent()` do CURLOPT_HTTPHEADER w:
         - `edgeApiRequest()` (linia ~136)
         - `apiRequest()` (linia ~186)
    
    Uwaga: 3 klasy z tą samą 3-linijkową metodą to akceptowalne — nie tworzyć traita dla tak prostej logiki.
  </action>
  <verify>Grep za "User-Agent" w obu plikach — po 1-2 wystąpienia w HTTPHEADER + metoda buildUserAgent</verify>
  <done>AC-2 i AC-3 satisfied: OAuth i tracking wysyłają User-Agent</done>
</task>

</tasks>

<boundaries>

## DO NOT CHANGE
- Logika biznesowa requestów (payloady, URL-e, obsługa odpowiedzi)
- Inne nagłówki HTTP (Accept, Content-Type, Authorization)
- Klienty API innych providerów (InPost, Apaczka, shopPRO)

## SCOPE LIMITS
- Nie refaktoryzować klientów HTTP do wspólnej klasy bazowej (to osobna faza 68)
- Nie zmieniać struktury klas — tylko dodanie metody i nagłówka
- URL dokumentacji (orderpro.pl/info) — strona nie musi istnieć na tym etapie, ale URL musi być poprawny

</boundaries>

<verification>
Before declaring plan complete:
- [ ] Grep "User-Agent" w AllegroApiClient.php zwraca 4+ wyniki
- [ ] Grep "User-Agent" w AllegroOAuthClient.php zwraca 1+ wynik
- [ ] Grep "User-Agent" w AllegroTrackingService.php zwraca 2+ wyniki
- [ ] .env.example zawiera APP_VERSION i ALLEGRO_USER_AGENT_URL
- [ ] Format User-Agent zgodny z wymaganiami Allegro: `NazwaAplikacji/Wersja (+URL)`
- [ ] Brak regresji w istniejących nagłówkach
</verification>

<success_criteria>
- Wszystkie 7 miejsc wysyłki requestów do Allegro zawiera nagłówek User-Agent
- Format zgodny z wymaganiami: `orderPRO/1.0.0 (+https://orderpro.pl/info)`
- Konfiguracja URL i wersji przez zmienne środowiskowe
- Brak zmian w logice biznesowej
</success_criteria>

<output>
After completion, create `.paul/phases/88-allegro-user-agent/88-01-SUMMARY.md`
</output>
