feat: Add User-Agent header to Allegro API requests

- Implemented buildUserAgent() method in AllegroApiClient, AllegroOAuthClient, and AllegroTrackingService to include User-Agent header in all HTTP requests to Allegro API. - Updated .env.example to include APP_VERSION and ALLEGRO_USER_AGENT_URL for configuration. - Created public /info page to provide application details required by Allegro, including app name, version, description, and contact information. - Added minimalist layout for public pages to ensure a professional appearance. - Ensured all changes comply with Allegro's API requirements for User-Agent header.
2026-04-08 20:59:55 +02:00
parent 0f7742f10d
commit c5b2885b44
21 changed files with 827 additions and 22 deletions
--- a/.paul/phases/88-allegro-user-agent/88-01-PLAN.md
+++ b/.paul/phases/88-allegro-user-agent/88-01-PLAN.md
@@ -0,0 +1,164 @@
+---
+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>
--- a/.paul/phases/88-allegro-user-agent/88-01-SUMMARY.md
+++ b/.paul/phases/88-allegro-user-agent/88-01-SUMMARY.md
@@ -0,0 +1,97 @@
+---
+phase: 88-allegro-user-agent
+plan: 01
+subsystem: api
+tags: [allegro, user-agent, curl, http-headers]
+
+requires: []
+provides:
+  - User-Agent header in all Allegro API requests
+affects: []
+
+tech-stack:
+  added: []
+  patterns: [buildUserAgent() per Allegro HTTP client class]
+
+key-files:
+  created: []
+  modified:
+    - src/Modules/Settings/AllegroApiClient.php
+    - src/Modules/Settings/AllegroOAuthClient.php
+    - src/Modules/Shipments/AllegroTrackingService.php
+
+key-decisions:
+  - "buildUserAgent() duplicated in 3 classes instead of trait — too simple to abstract"
+
+patterns-established: []
+
+duration: ~5min
+started: 2026-04-08T00:00:00Z
+completed: 2026-04-08T00:05:00Z
+---
+
+# Phase 88 Plan 01: Allegro User-Agent Summary
+
+**Dodanie naglowka User-Agent do wszystkich requestow HTTP do Allegro REST API zgodnie z art. 3.4.c Regulaminu (deadline: 30.06.2026)**
+
+## Performance
+
+| Metric | Value |
+|--------|-------|
+| Duration | ~5min |
+| Tasks | 3 completed |
+| Files modified | 5 |
+
+## Acceptance Criteria Results
+
+| Criterion | Status | Notes |
+|-----------|--------|-------|
+| AC-1: User-Agent w requestach REST API | Pass | 4 metody w AllegroApiClient (postJson, putJson, postBinary, requestJson) |
+| AC-2: User-Agent w requestach OAuth | Pass | 1 metoda w AllegroOAuthClient (requestToken) |
+| AC-3: User-Agent w requestach tracking | Pass | 2 metody w AllegroTrackingService (edgeApiRequest, apiRequest) |
+| AC-4: Konfigurowalnosc User-Agent | Pass | APP_VERSION i ALLEGRO_USER_AGENT_URL w .env/.env.example |
+
+## Accomplishments
+
+- Dodano naglowek `User-Agent: orderPRO/1.0.0 (+https://orderpro.pl/info)` do 7 miejsc wysylki requestow do Allegro API
+- Konfiguracja wersji i URL przez zmienne srodowiskowe (.env)
+- Metoda `buildUserAgent()` w kazdej z 3 klas klienckich
+
+## Files Created/Modified
+
+| File | Change | Purpose |
+|------|--------|---------|
+| `.env.example` | Modified | Dodano APP_VERSION i ALLEGRO_USER_AGENT_URL |
+| `.env` | Modified | Dodano APP_VERSION i ALLEGRO_USER_AGENT_URL |
+| `src/Modules/Settings/AllegroApiClient.php` | Modified | buildUserAgent() + User-Agent w 4 metodach HTTP |
+| `src/Modules/Settings/AllegroOAuthClient.php` | Modified | buildUserAgent() + User-Agent w requestToken() |
+| `src/Modules/Shipments/AllegroTrackingService.php` | Modified | buildUserAgent() + User-Agent w 2 metodach HTTP |
+
+## Decisions Made
+
+| Decision | Rationale | Impact |
+|----------|-----------|--------|
+| buildUserAgent() w kazdej klasie osobno | 3-linijkowa metoda, trait byloby overengineering | Brak wspolnego kodu, ale prostota |
+| URL domyslny: orderpro.pl/info | Zgodny z wymaganiami Allegro, konfigurowalny przez .env | Strona moze nie istniec jeszcze |
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+
+None.
+
+## Next Phase Readiness
+
+**Ready:**
+- Integracja Allegro w pelni zgodna z wymaganiami User-Agent od 01.07.2026
+
+**Concerns:**
+- Strona https://orderpro.pl/info powinna byc utworzona przed 30.06.2026
+
+**Blockers:** None
+
+---
+*Phase: 88-allegro-user-agent, Plan: 01*
+*Completed: 2026-04-08*