# adsPRO — Lista klas i metod

## Spis tresci

- [Klasy bazowe (autoload/)](#klasy-bazowe-autoload)
- [Kontrolery (autoload/controls/)](#kontrolery-autoloadcontrols)
- [Factory (autoload/factory/)](#factory-autoloadfactory)
- [Services (autoload/services/)](#services-autoloadservices)
- [View (autoload/view/)](#view-autoloadview)

---

## Klasy bazowe (`autoload/`)

### Klasa `Cache` (`autoload/class.Cache.php`)
- `store( $key, $data, $ttl )` — Zapisuje dane do pliku cache ze skompresowana serializacja i czasem wygasniecia (domyslnie 24h).
- `get_file_name( $key )` — Generuje sciezke pliku cache na podstawie hasha MD5 klucza, tworzac katalogi jesli nie istnieja.
- `fetch( $key )` — Pobiera dane z cache; zwraca `false` jesli plik nie istnieje, jest uszkodzony lub wygasl.

### Klasa `Chunk` (`autoload/class.Chunk.php`)
- `__construct( $file, $options )` — Otwiera plik XML do odczytu fragmentami, ustawiajac opcje (sciezka, element, rozmiar chunka).
- `__destruct()` — Zamyka uchwyt pliku przy niszczeniu obiektu.
- `read()` — Odczytuje i zwraca nastepne wystapienie wskazanego elementu XML z pliku (lub caly plik, jesli element nie podany).

### Klasa `Cron` (`autoload/class.Cron.php`)
- `recursive_tasks()` — Tworzy nowe instancje zadan cyklicznych (dzienne/miesieczne/roczne) na podstawie zadan z uplynietym terminem, kopiujac przypisania i akcje.
- `tasks_emails()` — Wysyla e-mailowe przypomnienia o zadaniach do przypisanych uzytkownikow zgodnie z ustawionym interwalam przypomnien.

### Klasa `DbModel` (`autoload/class.DbModel.php`)
- `__construct( $id )` — Laduje rekord z bazy danych po kluczu glownym i mapuje kolumny na wlasciwosci obiektu.
- `__get( $variable )` — Zwraca wartosc z wewnetrznej tablicy danych po nazwie pola.
- `__set( $variable, $value )` — Ustawia wartosc w wewnetrznej tablicy danych.
- `save()` — Zapisuje obiekt do bazy: aktualizuje istniejacy rekord lub wstawia nowy (i ustawia ID).
- `delete()` — Usuwa rekord z bazy danych na podstawie klucza glownego obiektu.

### Klasa `Excel` (`autoload/class.Excel.php`)
- `filename( $title )` — Konwertuje tytul na bezpieczna nazwe pliku (lowercase, bez znakow specjalnych).
- `__construct( $title )` — Tworzy nowy arkusz Excel z podanym tytulem i zapisuje znacznik poczatku pliku (BOF).
- `headers()` — Wysyla naglowki HTTP wymuszajace pobranie pliku XLS przez przegladarke.
- `send_to_file( $loc )` — Zapisuje dane arkusza do pliku na dysku pod wskazana sciezka.
- `send()` — Wysyla arkusz XLS do przegladarki jako plik do pobrania.
- `bofMarker()` — Zapisuje binarny znacznik poczatku pliku Excel (BOF).
- `eofMarker()` — Zapisuje binarny znacznik konca pliku Excel (EOF).
- `left( $amount )` — Przesuwa wewnetrzny kursor o podana liczbe kolumn w lewo.
- `right( $amount )` — Przesuwa wewnetrzny kursor o podana liczbe kolumn w prawo.
- `up( $amount )` — Przesuwa wewnetrzny kursor o podana liczbe wierszy w gore.
- `down( $amount )` — Przesuwa wewnetrzny kursor o podana liczbe wierszy w dol.
- `top()` — Ustawia kursor na pierwszym wierszu (wiersz 0).
- `home()` — Ustawia kursor na pierwszej kolumnie (kolumna 0).
- `number( $value )` — Zapisuje wartosc liczbowa do biezacej komorki arkusza.
- `label( $value )` — Zapisuje wartosc tekstowa do biezacej komorki arkusza.

### Klasa `Html` (`autoload/class.Html.php`)
- `form_text( $params )` — Renderuje komponent formularza tekstowego z etykieta na podstawie szablonu `html/form-text`.
- `input_switch( $params )` — Renderuje komponent przelacznika (switch) na podstawie szablonu `html/input-switch`.
- `select( $params )` — Renderuje pole wyboru (select/dropdown) na podstawie szablonu `html/select`.
- `textarea( $params )` — Renderuje pole tekstowe wieloliniowe (textarea) z domyslna liczba 4 wierszy.
- `input_icon( $params )` — Renderuje pole input z ikona na podstawie szablonu `html/input-icon`.
- `input( $params )` — Renderuje standardowe pole input (domyslnie typu text) na podstawie szablonu `html/input`.
- `button( $params )` — Renderuje przycisk z domyslna klasa `btn-sm btn-info`.
- `panel( $params )` — Renderuje panel z tytulem, klasa CSS i trescia na podstawie szablonu `html/panel`.

### Klasa `S` (`autoload/class.S.php`)
- `array_unique_multi( $array, $key )` — Usuwa duplikaty z tablicy wielowymiarowej na podstawie wartosci wskazanego klucza.
- `to_decimal( $number, $no_of_decimals )` — Formatuje liczbe do postaci dziesietnej z separatorem i dwoma miejscami po przecinku.
- `number_display( $value )` — Formatuje kwote do wyswietlenia w formacie polskim z symbolem "zl" (np. `1 234,56 zl`).
- `prepar_request( $query )` — Konwertuje tablice parametrow na zakodowany query string URL.
- `seo( $val, $delete_rhombs )` — Generuje slug SEO-friendly z tekstu (usuwanie polskich znakow, zamiana spacji na myslniki, lowercase).
- `no_pl_excel( $val )` — Zamienia polskie znaki diakrytyczne na odpowiedniki ASCII (wersja dla Excela).
- `noPL( $val )` — Transliteruje znaki cyrylicy i polskie diakrytyki na ASCII za pomoca iconv.
- `alert( $text )` — Ustawia komunikat alertu w sesji do wyswietlenia przy nastepnym zaladowaniu strony.
- `hash( $qtd )` — Generuje losowy ciag alfanumeryczny o podanej dlugosci.
- `sort_array_of_array( &$array, $subfield, $type )` — Sortuje tablice tablic po wskazanym podkluczu (rosnaco lub malejaco).
- `json_to_array( $json )` — Konwertuje JSON w formacie jQuery `serializeArray()` (name/value) na tablice asocjacyjna.
- `get_session( $var )` — Zwraca wartosc zmiennej z sesji PHP.
- `del_session( $var )` — Usuwa zmienna z sesji PHP.
- `set_session( $var, $val )` — Ustawia wartosc zmiennej w sesji PHP.
- `get( $var )` — Pobiera wartosc parametru z POST lub GET (POST ma priorytet).
- `pre( $data, $type )` — Wyswietla dane w tagu `<pre>` z kolorowym formatowaniem do debugowania.
- `email_check( $email )` — Waliduje adres e-mail za pomoca `FILTER_VALIDATE_EMAIL`.
- `send_email( $email, $subject, $text, $file )` — Wysyla e-mail przez SMTP (PHPMailer) z opcjonalnymi zalacznikami.

### Klasa `Tpl` (`autoload/class.Tpl.php`)
- `__construct( $dir )` — Inicjalizuje obiekt szablonu z opcjonalnym katalogiem (domyslnie `templates/`).
- `view( $file, $values )` — Statyczna metoda skrotowa: tworzy obiekt Tpl, przypisuje zmienne i renderuje szablon.
- `secureHTML( $val )` — Escapuje znaki specjalne HTML (cudzyslow, nawiasy katowe) w celu ochrony przed XSS.
- `render( $file )` — Renderuje plik szablonu PHP (szuka kolejno w `templates_user/`, `templates/`, sciezce bezwzglednej) i zwraca HTML.
- `__set( $name, $value )` — Ustawia zmienna szablonu w wewnetrznej tablicy.
- `__isset( $name )` — Sprawdza czy zmienna szablonu jest ustawiona.
- `__get( $name )` — Pobiera wartosc zmiennej szablonu z wewnetrznej tablicy.

---

## Kontrolery (`autoload/controls/`)

### Klasa `\controls\Allegro` (`autoload/controls/class.Allegro.php`)
- `main_view()` — Wyswietla glowny widok modulu Allegro z lista klientow i podsumowaniem ostatniego importu.
- `import_data()` — Importuje dane z pliku CSV Allegro: parsuje wiersze, tworzy klientow i produkty, zapisuje lub aktualizuje historie statystyk.

### Klasa `\controls\Api` (`autoload/controls/class.Api.php`)
- `campaigns_data_save()` — Przyjmuje dane kampanii z API (JSON), tworzy/aktualizuje kampanie i ich historie (ROAS, budzet, wydatki, strategia) dla podanego klienta i daty.
- `phrases_data_save()` — Przyjmuje dane fraz wyszukiwania z API (JSON), tworzy/aktualizuje frazy i ich dzienne statystyki.
- `products_data_save()` — Przyjmuje dane produktow z API (JSON), tworzy/aktualizuje produkty i ich dzienne statystyki.
- `products_data_import()` — Rozszerzony import danych produktow z API: obsluguje scope kampania/grupa reklam, przelicza agregaty 30-dniowe i products_temp po imporcie.
- `rebuild_products_temp_for_client()` (private) — Deleguje przebudowe tabeli agregatow produktow do `Cron::rebuild_products_temp_for_client()`.
- `normalize_number()` (private) — Normalizuje wartosc liczbowa z roznych formatow (przecinki, kropki, waluty) do typu float.

### Klasa `\controls\CampaignAlerts` (`autoload/controls/class.CampaignAlerts.php`)
- `redirect_to_main_view()` (private) — Przekierowuje do widoku alertow kampanii z zachowaniem filtru klienta i numeru strony.
- `main_view()` — Wyswietla stronicowana liste alertow kampanii z filtrem klienta, oznacza wszystkie jako widziane i usuwa stare alerty (30 dni).
- `delete_selected()` — Usuwa zaznaczone alerty kampanii po ich identyfikatorach i przekierowuje z komunikatem o wyniku operacji.

### Klasa `\controls\Campaigns` (`autoload/controls/class.Campaigns.php`)
- `main_view()` — Wyswietla glowny widok kampanii z lista klientow.
- `get_campaigns_list()` — Zwraca liste kampanii (JSON) dla wybranego klienta do zaladowania w interfejsie.
- `get_campaign_history_data_table()` — Zwraca dane historyczne kampanii (JSON) w formacie DataTables z paginacja serwerowa.
- `get_campaign_history_data_table_chart()` — Zwraca dane historyczne kampanii (JSON) w formacie przygotowanym do wykresu Highcharts.
- `get_campaign_ad_groups()` — Zwraca liste grup reklam (JSON) dla wybranej kampanii.
- `get_campaign_phrase_details()` — Zwraca frazy wyszukiwania i slowa kluczowe wykluczajace (JSON) dla kampanii i opcjonalnie grupy reklam.
- `delete_campaign()` — Usuwa pojedyncza kampanie po ID i zwraca wynik operacji (JSON).
- `delete_campaigns()` — Usuwa wiele kampanii na podstawie tablicy ID i zwraca liczbe usunietych (JSON).
- `delete_history_entry()` — Usuwa pojedynczy wpis z historii kampanii po ID.
- `delete_history_entries()` — Usuwa wiele wpisow z historii kampanii na podstawie tablicy ID.

### Klasa `\controls\CampaignTerms` (`autoload/controls/class.CampaignTerms.php`)
- `is_google_ads_debug_enabled()` (private) — Sprawdza czy tryb debug Google Ads jest wlaczony w ustawieniach.
- `with_optional_debug()` (private) — Dolacza dane debugowe do payloadu odpowiedzi, jezeli tryb debug jest aktywny.
- `normalize_ai_recommendations()` (private) — Przetwarza surowy JSON rekomendacji AI (exclude/keep) na znormalizowana tablice z danymi frazy i uzasadnieniem.
- `main_view()` — Wyswietla glowny widok zarzadzania frazami kampanii z lista klientow.
- `get_campaigns_list()` — Zwraca liste kampanii (JSON) z typem kanalu reklamowego dla wybranego klienta.
- `get_campaign_ad_groups()` — Zwraca liste grup reklam (JSON) dla wybranej kampanii.
- `get_campaign_phrase_details()` — Zwraca frazy wyszukiwania, slowa kluczowe wykluczajace oraz keywords (JSON) dla kampanii i grupy reklam.
- `add_negative_keyword()` — Dodaje fraze wykluczajaca w Google Ads (na poziomie kampanii lub grupy reklam) przez API i zapisuje lokalnie.
- `analyze_search_terms_with_ai()` — Analizuje frazy wyszukiwania kampanii przy uzyciu OpenAI i zwraca rekomendacje wykluczenia/zachowania z uzasadnieniem.
- `delete_negative_keyword_row()` (private) — Usuwa pojedyncza fraze wykluczajaca z Google Ads przez API i z lokalnej bazy danych.
- `delete_negative_keyword()` — Obsluguje zadanie usuniecia jednej frazy wykluczajacej (endpoint JSON).
- `delete_negative_keywords()` — Usuwa wiele fraz wykluczajacych iteracyjnie, zwraca podsumowanie udanych i nieudanych operacji.
- `update_keyword_match_type()` — Zmienia typ dopasowania slowa kluczowego (PHRASE/EXACT/BROAD) w Google Ads przez API i aktualizuje lokalnie.
- `add_keyword()` — Dodaje nowe slowo kluczowe do grupy reklam w Google Ads przez API i zapisuje lokalnie.
- `delete_keyword()` — Usuwa slowo kluczowe z grupy reklam w Google Ads przez API i z lokalnej bazy.

### Klasa `\controls\Clients` (`autoload/controls/class.Clients.php`)
- `get_facebook_conversion_window_days()` (private) — Pobiera okno konwersji Facebook Ads (w dniach) z ustawien lub konfiguracji, max 90.
- `normalize_facebook_ads_account_id()` (private) — Normalizuje ID konta Facebook Ads do formatu `act_DIGITS`.
- `clients_has_deleted_column()` (private) — Sprawdza czy tabela `clients` posiada kolumne `deleted` (z cache'owaniem wyniku).
- `sql_clients_not_deleted()` (private) — Generuje fragment SQL filtrujacy nieusunietych klientow (z opcjonalnym aliasem tabeli).
- `main_view()` — Wyswietla glowny widok listy klientow.
- `save()` — Tworzy nowego klienta lub aktualizuje istniejacego na podstawie danych z formularza.
- `set_active()` — Przelacza status aktywnosci klienta (aktywny/nieaktywny) i zwraca wynik (JSON).
- `delete()` — Usuwa klienta po ID i zwraca potwierdzenie (JSON).
- `get()` — Pobiera dane pojedynczego klienta po ID i zwraca jako JSON.
- `sync_status()` — Zwraca aktualny status synchronizacji (kampanie, produkty, Merchant, Facebook Ads) per klient jako JSON.
- `force_sync()` — Wymusza ponowna synchronizacje wybranego pipeline'u (kampanie, produkty, Merchant, Facebook Ads) dla klienta.

### Klasa `\controls\FacebookAds` (`autoload/controls/class.FacebookAds.php`)
- `sanitize_level()` (private) — Normalizuje poziom encji Facebook Ads (campaign/adset/ad) z walidacja, domyslnie `campaign`.
- `main_view()` — Wyswietla glowny widok raportow Facebook Ads z lista klientow.
- `get_entities()` — Zwraca liste encji Facebook Ads (kampanie, adsets, reklamy) z ostatnimi metrykami dla wybranego klienta i poziomu (JSON).
- `get_history_data_table()` — Zwraca dane historyczne encji Facebook Ads w formacie DataTables z paginacja serwerowa (JSON).
- `get_history_data_chart()` — Zwraca dane historyczne encji Facebook Ads w formacie przygotowanym do wykresu Highcharts (JSON).

### Klasa `\controls\Logs` (`autoload/controls/class.Logs.php`)
- `main_view()` — Wyswietla glowny widok logow aplikacji z lista dostepnych zrodel.
- `get_logs_data_table()` — Zwraca logi w formacie DataTables (JSON) z filtrami poziomu, zrodla i zakresu dat.
- `get_detail()` — Zwraca pelne szczegoly pojedynczego wpisu logu (message, context JSON, zrodlo) po ID.

### Klasa `\controls\Products` (`autoload/controls/class.Products.php`)
- `normalize_keyword_source_url()` (private) — Normalizuje URL zrodla fraz kluczowych (lowercase scheme/host, zachowanie query string).
- `sync_product_fields_to_merchant()` — Synchronizuje zmienione pola produktu (tytul, opis, kategoria, custom_label_4) z Google Merchant Center przez API.
- `main_view()` — Wyswietla glowny widok listy produktow z filtrem klientow.
- `get_campaigns_list()` — Zwraca liste kampanii (JSON) ograniczona do typow SHOPPING i PERFORMANCE_MAX dla wybranego klienta.
- `get_campaign_ad_groups()` — Zwraca liste grup reklam (JSON) dla wybranej kampanii.
- `get_scope_alerts()` — Zwraca alerty produktowe (JSON) dla wybranego scope'u (klient, kampania, grupa reklam).
- `get_products_without_impressions_30()` — Zwraca liste produktow bez wyswietlen w ostatnich 30 dniach dla danego scope'u (JSON).
- `delete_campaign_ad_group()` — Usuwa grupe reklam lokalnie i opcjonalnie w Google Ads (tylko kampanie Shopping).
- `assign_product_scope()` — Przypisuje produkt do kampanii i grupy reklam Google Ads (tworzac nowe lub wybierajac istniejace) z synchronizacja do Google Ads API.
- `comment_add()` — Dodaje komentarz do produktu z opcjonalna data.
- `comment_delete()` — Usuwa komentarz produktu po ID.
- `get_product_data()` — Zwraca szczegolowe dane produktu (tytul, opis, kategoria, URL) jako JSON.
- `get_product_merchant_sync_logs()` — Zwraca logi synchronizacji produktu z Merchant Center (JSON) z limitem wpisow.
- `ai_suggest()` — Generuje sugestie AI (tytul, opis lub kategorie) dla produktu przy uzyciu OpenAI, Claude lub Gemini, z opcjonalnym wzbogaceniem o frazy z Keyword Planner.
- `get_products()` — Zwraca liste produktow w formacie DataTables (JSON) z sortowaniem, wyszukiwaniem, paskiem ROAS i algorytmem ostrzezen.
- `delete_product()` — Usuwa pojedynczy produkt po ID.
- `delete_products()` — Usuwa wiele produktow na podstawie tablicy ID.
- `save_min_roas()` — Zapisuje minimalny prog ROAS dla produktu.
- `get_distinct_cl4()` — Zwraca unikalne wartosci custom_label_4 dla klienta (JSON).
- `save_custom_label_4()` — Zapisuje etykiete custom_label_4 produktu, synchronizuje z Merchant Center i dodaje komentarz.
- `product_history()` — Wyswietla widok historii pojedynczego produktu z kontekstem kampanii i grupy reklam.
- `get_product_history_table()` — Zwraca historie dziennych statystyk produktu w formacie DataTables (JSON) z obliczonym ROAS i komentarzami.
- `get_product_history_table_chart()` — Zwraca dane historii 30-dniowej produktu w formacie przygotowanym do wykresu Highcharts (JSON).
- `save_product_data()` — Zapisuje edytowane dane produktu (tytul, opis, kategoria, URL) i synchronizuje zmiany z Merchant Center.

### Klasa `\controls\Site` (`autoload/controls/class.Site.php`)
- `route()` — Glowny router aplikacji: mapuje parametry module/action z URL na odpowiednia metode kontrolera i ja wywoluje.

### Klasa `\controls\Users` (`autoload/controls/class.Users.php`)
- `permissions()` — Sprawdza uprawnienia uzytkownika do modulu/akcji na podstawie hardkodowanej mapy uprawnien.
- `logout()` — Wylogowuje uzytkownika: usuwa cookie, niszczy sesje i przekierowuje na strone glowna.
- `settings_save()` — Zapisuje ustawienia Pushover API uzytkownika i odswierza dane sesji.
- `settings()` — Wyswietla strone ustawien z danymi uzytkownika i dashboardem statusu CRON.
- `settings_cron_status()` — Zwraca aktualny status CRON (JSON) do odswiezania dashboardu AJAX-em.
- `settings_save_google_ads()` — Zapisuje ustawienia API Google Ads (developer token, client ID/secret, refresh token, manager account) i czysci cache tokenow.
- `settings_save_openai()` — Zapisuje ustawienia OpenAI (klucz API, model, wlacz/wylacz).
- `settings_save_claude()` — Zapisuje ustawienia Claude AI (klucz API, model, wlacz/wylacz).
- `settings_save_gemini()` — Zapisuje ustawienia Gemini AI (klucz API, model, wlacz/wylacz).
- `settings_save_ai_prompts()` — Zapisuje niestandardowe szablony promptow AI dla tytulow i opisow produktow.
- `get_cron_dashboard_data()` (private) — Buduje kompletne dane dashboardu CRON: postep kampanii, produktow, Merchant i Facebook Ads, endpointy, ETA zakonczenia.
- `progress_percent()` (private) — Oblicza procent postepu (0-100) z zabezpieczeniem przed dzieleniem przez zero.
- `build_eta_meta()` (private) — Szacuje czas zakonczenia zadania CRON na podstawie sredniej czestotliwosci wywolan i pozostalych zadan.
- `format_duration_short()` (private) — Formatuje czas trwania w sekundach do czytelnej formy (np. "2 h 15 min").
- `format_datetime()` (private) — Formatuje wartosc datetime do standardowego formatu `Y-m-d H:i:s` lub zwraca "Brak danych".
- `get_base_url()` (private) — Buduje bazowy URL aplikacji (scheme + host) z danych serwera.
- `login()` — Autoryzuje uzytkownika (email + MD5 hasla), ustawia sesje i opcjonalnie cookie "zapamietaj mnie".
- `login_form()` — Wyswietla formularz logowania.

### Klasa `\controls\Cron` (`autoload/controls/class.Cron.php`)
- `cron_universal()` — Glowny pipeline CRON: synchronizuje kampanie, frazy, produkty, grupy reklam i URL-e Merchant dla jednego klienta i jednego dnia na wywolanie.
- `cron_products_urls()` — Osobny CRON do pobierania URL-ow produktow z Google Merchant Center dla klientow, ktorym brakuje linkow.
- `get_products_url_sync_diagnostics_for_client()` (private) — Zwraca diagnostyke stanu synchronizacji URL-ow produktow klienta (ile z URL, ile brakujacych, ile not_found).
- `get_products_missing_url_for_client()` (private) — Pobiera liste produktow klienta bez URL-a (lub z flaga not_found do ponownego sprawdzenia po 7 dniach).
- `sync_products_urls_and_alerts_for_client()` (private) — Synchronizuje URL-e produktow z Merchant Center i tworzy alerty dla produktow nieznalezionych.
- `sync_products_fetch_for_client()` (private) — Pobiera dane produktow z Google Ads API dla klienta na dany dzien i zapisuje/aktualizuje historie.
- `resolve_products_scope_ids()` — Mapuje zewnetrzne ID kampanii i grupy reklam na lokalne ID w bazie danych, tworzac rekordy jezeli nie istnieja.
- `ensure_products_campaign()` (private) — Upewnia sie ze kampania istnieje w bazie (tworzy jezeli brakuje) i zwraca jej lokalne ID.
- `ensure_products_ad_group()` (private) — Upewnia sie ze grupa reklam istnieje w bazie (tworzy jezeli brakuje) i zwraca jej lokalne ID.
- `aggregate_products_history_30_for_client()` (private) — Przelicza srednie 30-dniowe dla wszystkich zaktualizowanych produktow klienta i zapisuje do products_history_30.
- `rebuild_products_aggregate_for_client()` (private) — Przebudowuje tabele products_aggregate ze statystykami 30-dniowymi i all-time dla wszystkich produktow klienta.
- `rebuild_products_temp_for_client()` — Zwraca liczbe wierszy w products_aggregate dla klienta (po wycofaniu tabeli products_temp).
- `get_roas_all_time()` — Oblicza ROAS all-time produktu dla konkretnego scope'u (kampania/grupa reklam) na podstawie historii.
- `cron_product_history_30_save()` — Zapisuje/aktualizuje srednia 30-dniowa statystyke produktu (impressions, clicks, cost, conversions, ROAS) dla scope'u.
- `cron_campaigns_product_alerts_merchant()` — CRON walidujacy produkty w Merchant Center: sprawdza brakujace produkty i tworzy alerty kampanijne per klient.
- `build_campaigns_db_map_for_client()` (private) — Buduje mape kampanii klienta (external_campaign_id -> db_campaign_id).
- `get_sync_phase_for_client_date()` (private) — Pobiera aktualna faze synchronizacji (pending/done/fetch/...) dla pipeline'u, daty i klienta.
- `get_next_client_id_in_order()` (private) — Zwraca ID nastepnego klienta w kolejnosci z listy, z zawijaniem na poczatek.
- `sync_campaigns_snapshot_for_client()` (private) — Pobiera snapshot kampanii (30 dni + all-time) z Google Ads API i zapisuje historie z ROAS, budzetem i strategia.
- `sync_campaign_terms_backfill_for_client()` (private) — Synchronizuje frazy wyszukiwania kampanii (search terms) dla wielu dat wstecz i przelicza agregaty.
- `sync_campaign_keywords_and_negatives_for_client()` (private) — Synchronizuje slowa kluczowe i slowa kluczowe wykluczajace kampanii klienta z Google Ads API.
- `sync_product_campaign_alerts_for_client()` (private) — Generuje alerty produktowe kampanii (brak w Merchant, brak mapowania) przez porownanie ofert z Google Ads i Merchant Center.
- `log_product_alerts_debug()` (private) — Loguje informacje debugowe procesu alertow produktowych do tabeli logow.
- `merge_shopping_ad_group_offer_rows()` (private) — Scala dwa zbiory wierszy ofert grup reklam Shopping (uzupelnia brakujace offer_id).
- `normalize_offer_id_for_lookup()` (private) — Normalizuje offer_id do postaci lookup (lowercase, trimmed) uzywany przy porownywaniu.
- `normalize_offer_id_for_compare()` (private) — Normalizuje offer_id do porownania (lowercase, trim, usun prefix `online:pl:`).
- `build_offer_id_lookup_variants()` (private) — Buduje warianty offer_id do wyszukiwania (z prefiksem i bez, rozne formaty).
- `get_shopping_ad_group_offer_ids_from_history()` (private) — Pobiera offer_id produktow z historii dla kampanii Shopping na podstawie products_history.
- `sync_campaign_ad_groups_for_client()` (private) — Synchronizuje grupy reklam (i grupy zasobow PMAX) z Google Ads API i zapisuje/aktualizuje w bazie.
- `sync_campaign_search_terms_for_client()` (private) — Synchronizuje frazy wyszukiwania kampanii z Google Ads API i zapisuje do bazy (agregacja all-time).
- `build_ad_group_db_map_from_db()` (private) — Buduje mape grup reklam z bazy danych (external_ad_group_id -> db_ad_group_id) dla podanych kampanii.
- `sync_campaign_search_terms_daily()` (private) — Synchronizuje dzienne statystyki fraz wyszukiwania z Google Ads API dla konkretnej daty.
- `aggregate_campaign_search_terms_for_client()` (private) — Przelicza agregaty all-time i 30-dniowe dla fraz wyszukiwania kampanii klienta.
- `ensure_campaign_level_ad_group()` (private) — Tworzy zastepczy rekord grupy reklam na poziomie kampanii (dla kampanii PMAX bez grup).
- `sync_campaign_keywords_for_client()` (private) — Synchronizuje slowa kluczowe kampanii klienta z Google Ads API i zapisuje/aktualizuje w bazie.
- `sync_campaign_negative_keywords_for_client()` (private) — Synchronizuje slowa kluczowe wykluczajace kampanii klienta z Google Ads API i zapisuje/aktualizuje w bazie.
- `pick_clients_batch_by_cursor()` (private) — Wybiera paczke klientow do przetworzenia na podstawie kursora (last processed client ID), z zawijaniem na poczatek listy.
- `ensure_sync_rows()` (private) — Tworzy brakujace wiersze statusu synchronizacji w `cron_sync_status` dla pipeline'u, dat i klientow.
- `get_active_sync_date()` (private) — Pobiera aktywna (najstarsza nieukonczona) date synchronizacji dla danego pipeline'u.
- `get_pending_clients()` (private) — Pobiera liste klientow w danej fazie synchronizacji dla pipeline'u i daty.
- `mark_sync_phase()` (private) — Oznacza faze synchronizacji (pending/done/fetch/...) dla klienta, pipeline'u i daty z opcjonalnym komunikatem bledu.
- `determine_products_phase()` (private) — Okresla biezaca faze pipeline'u produktow dla aktywnej daty synchronizacji.
- `get_active_client()` (private) — Zwraca ID nastepnego klienta do przetworzenia w pipeline (z najstarsza nieukonczona data).
- `get_pending_dates_for_client()` (private) — Pobiera nieprzetworzone daty synchronizacji dla klienta w danym pipeline z limitem.
- `determine_client_products_phase()` (private) — Okresla faze synchronizacji produktow dla konkretnego klienta.
- `cron_facebook_ads()` — Glowny endpoint CRON dla synchronizacji Facebook Ads: deleguje do `run_facebook_ads_sync_payload()`.
- `run_facebook_ads_sync_payload()` (private) — Pobiera dane kampanii, adsets i reklam z Facebook Ads API dla aktywnych klientow (30 dni), z blokada ponownego pobrania w danym dniu.
- `cleanup_old_sync_rows()` (private) — Usuwa stare wiersze z tabeli `cron_sync_status` starsze niz podana liczba dni.
- `get_conversion_window_days()` (private) — Pobiera wielkosc okna konwersji (w dniach) z ustawien/konfiguracji do backfill synchronizacji Google Ads.
- `get_facebook_conversion_window_days()` (private) — Pobiera okno konwersji Facebook Ads (w dniach) z ustawien lub konfiguracji.
- `cleanup_pipeline_rows_outside_window()` (private) — Usuwa wiersze synchronizacji dla dat poza aktualnym oknem (nie nalezacych do listy `sync_dates`).
- `build_backfill_dates()` (private) — Buduje tablice dat do backfill synchronizacji od `end_date` wstecz o `window_days` dni.
- `is_debug_requested()` (private) — Sprawdza czy w parametrach zadania jest flaga debug (1/true/yes/on).
- `output_cron_response()` (private) — Formatuje i wysyla odpowiedz CRON (JSON lub HTML debug), loguje wynik do tabeli logow.
- `clients_has_column()` (private) — Sprawdza czy tabela `clients` posiada dana kolumne (z cache'owaniem).
- `sql_clients_not_deleted()` (private) — Generuje fragment SQL filtrujacy nieusunietych klientow (z opcjonalnym aliasem).
- `sql_clients_deleted()` (private) — Generuje fragment SQL filtrujacy usunietych klientow (z opcjonalnym aliasem).
- `get_setting_value()` (private) — Pobiera wartosc ustawienia z tabeli `settings` (lub domyslna jezeli nie istnieje).
- `set_setting_value()` (private) — Zapisuje lub aktualizuje wartosc ustawienia w tabeli `settings`.
- `touch_cron_invocation()` (private) — Rejestruje czas wywolania CRON-a, oblicza i zapisuje sredni interwal miedzy wywolaniami (do szacowania ETA).
- `format_bidding_strategy()` (private) — Formatuje typ strategii bidding Google Ads na czytelna etykiete po polsku z opcjonalnym docelowym ROAS.
- `cron_phrase_history_30_save()` — Oblicza i zapisuje srednia 30-dniowa statystyke frazy (impressions, clicks, cost, ROAS) do tabeli phrases_history_30.

---

## Factory (`autoload/factory/`)

### Klasa `\factory\CampaignAlerts` (`autoload/factory/class.CampaignAlerts.php`)
- `get_alerts_count( $client_id )` — Zwraca liczbe alertow kampanii, opcjonalnie filtrowanych po kliencie.
- `get_unseen_count()` — Zwraca liczbe nieodczytanych alertow.
- `mark_all_seen()` — Oznacza wszystkie alerty jako odczytane.
- `get_clients()` — Pobiera liste aktywnych klientow (id i nazwa) do filtra alertow.
- `get_alerts( $client_id, $limit, $offset )` — Pobiera stronicowana liste alertow z danymi kampanii i klienta (JOIN).
- `delete_old_alerts( $days )` — Usuwa alerty starsze niz podana liczba dni (domyslnie 30).
- `delete_alerts( array $ids )` — Usuwa alerty o podanych identyfikatorach i zwraca liczbe usunietych.

### Klasa `\factory\Campaigns` (`autoload/factory/class.Campaigns.php`)
- `get_clients()` — Pobiera liste wszystkich klientow posortowanych po nazwie.
- `get_campaigns_list( $client_id, $only_active )` — Pobiera kampanie klienta, opcjonalnie tylko te aktywne (na podstawie najnowszej historii).
- `get_campaign_history_data( $campaign_id, $start, $length, $revert )` — Pobiera stronicowana historie kampanii z mozliwoscia odwrocenia sortowania.
- `get_records_total_campaign_history_data( $campaign_id )` — Zwraca laczna liczbe wpisow historii kampanii.
- `get_client_name( $client_id )` — Zwraca nazwe klienta po jego ID.
- `get_campaign_ad_groups( $campaign_id )` — Pobiera aktywne grupy reklam kampanii ze statystykami 30-dniowymi i all-time.
- `get_campaign_search_terms( $campaign_id, $ad_group_id )` — Pobiera frazy wyszukiwane kampanii ze statystykami, opcjonalnie filtrowane po grupie reklam.
- `get_campaign_negative_keywords( $campaign_id, $ad_group_id )` — Pobiera wykluczajace slowa kluczowe kampanii (scope: kampania lub grupa reklam).
- `get_campaign_keywords( $campaign_id, $ad_group_id )` — Pobiera slowa kluczowe kampanii ze statystykami, opcjonalnie filtrowane po grupie reklam.
- `get_search_term_context( $search_term_row_id )` — Pobiera pelny kontekst frazy wyszukiwanej (klient, kampania, external ID) potrzebny do operacji API.
- `upsert_campaign_negative_keyword( $campaign_id, $ad_group_id, $scope, $keyword_text, $match_type )` — Dodaje lub zwraca istniejace wykluczajace slowo kluczowe (upsert z deduplikacja).
- `get_negative_keyword_context( $negative_keyword_row_id )` — Pobiera kontekst wykluczajacego slowa kluczowego (klient, kampania, external ID) potrzebny do operacji API.
- `delete_campaign_negative_keyword( $negative_keyword_row_id )` — Usuwa lokalne wykluczajace slowo kluczowe po ID.
- `get_keyword_context( $keyword_id )` — Pobiera kontekst slowa kluczowego (klient, kampania, external ID) potrzebny do operacji API.
- `update_keyword_match_type( $keyword_id, $new_match_type )` — Aktualizuje typ dopasowania slowa kluczowego w lokalnej bazie.
- `insert_campaign_keyword( $campaign_id, $ad_group_id, $keyword_text, $match_type )` — Wstawia nowe slowo kluczowe kampanii do lokalnej bazy.
- `delete_campaign_keyword( $keyword_id )` — Usuwa slowo kluczowe kampanii z lokalnej bazy.
- `delete_campaign( $campaign_id )` — Usuwa kampanie wraz z jej historia.
- `delete_campaigns( array $ids )` — Usuwa wiele kampanii wraz z ich historiami i zwraca liczbe usunietych.
- `delete_history_entry( $history_id )` — Usuwa pojedynczy wpis historii kampanii.
- `delete_history_entries( $ids )` — Usuwa wiele wpisow historii kampanii.

### Klasa `\factory\Clients` (`autoload/factory/class.Clients.php`)
- `get_all()` — Pobiera liste wszystkich klientow posortowanych po nazwie.
- `get( $id )` — Pobiera dane pojedynczego klienta po ID.
- `create( $data )` — Tworzy nowego klienta i zwraca jego ID.
- `update( $id, $data )` — Aktualizuje dane klienta o podanym ID.
- `delete( $id )` — Usuwa klienta o podanym ID.

### Klasa `\factory\Cron` (`autoload/factory/class.Cron.php`)
- `remove_points_history()` — Usuwa historie punktow starsza niz 30 dni.
- `update_points()` — Dodaje 100 punktow uzytkownikom, ktorzy nie otrzymali ich dzisiaj.
- `send_push()` — Wysyla powiadomienia push (Pushover) o nowych ogloszeniach w roznych trybach czestotliwosci.
- `send_emails()` — Wysyla powiadomienia e-mail o nowych ogloszeniach w roznych trybach czestotliwosci.

### Klasa `\factory\FacebookAds` (`autoload/factory/class.FacebookAds.php`)
- `clients_has_deleted_column()` (private) — Sprawdza czy tabela clients posiada kolumne `deleted`.
- `sql_clients_not_deleted( $alias )` (private) — Generuje fragment SQL filtrujacy nieusunietych klientow.
- `get_clients_for_sync( $client_id )` — Pobiera aktywnych klientow z ustawionym Facebook Ads Account ID do synchronizacji.
- `sync_active_last_days_for_client( $client, $api, $days, $active_only )` — Synchronizuje dane Facebook Ads klienta z ostatnich N dni i zapisuje snapshot.
- `sync_active_date_for_client( $client, $api, $sync_date, $active_only )` — Synchronizuje dane Facebook Ads klienta za konkretna date i zapisuje snapshot.
- `sync_date_range_for_client( $client, $api, $since, $until, $active_only )` — Synchronizuje dane Facebook Ads klienta za zakres dat z danymi all-time i zapisuje snapshot.
- `save_snapshot( $client_id, $payload, $all_time_map )` (private) — Zapisuje pelny snapshot danych Facebook Ads (kampanie, zestawy reklam, reklamy + historia) w transakcji.
- `upsert_campaign( $client_id, $row )` (private) — Tworzy lub aktualizuje kampanie Facebook w bazie (INSERT ON DUPLICATE KEY UPDATE).
- `upsert_campaign_history( $campaign_db_id, $row, $roas_all_time )` (private) — Tworzy lub aktualizuje wpis historii kampanii Facebook.
- `upsert_ad_set( $client_id, $campaign_db_id, $row )` (private) — Tworzy lub aktualizuje zestaw reklam Facebook w bazie.
- `upsert_ad_set_history( $ad_set_db_id, $row )` (private) — Tworzy lub aktualizuje wpis historii zestawu reklam Facebook.
- `upsert_ad( $client_id, $campaign_db_id, $ad_set_db_id, $row )` (private) — Tworzy lub aktualizuje reklame Facebook w bazie.
- `upsert_ad_history( $ad_db_id, $row )` (private) — Tworzy lub aktualizuje wpis historii reklamy Facebook.
- `resolve_campaign_db_id( $client_id, $row, &$campaign_map )` (private) — Rozwiazuje lokalne ID kampanii Facebook z cache lub bazy.
- `resolve_ad_set_db_id( $client_id, $campaign_db_id, $row, &$ad_set_map )` (private) — Rozwiazuje lokalne ID zestawu reklam Facebook z cache lub bazy.
- `normalize_external_id( $value )` (private) — Wyciaga same cyfry z zewnetrznego identyfikatora.
- `normalize_date( $value )` (private) — Normalizuje date do formatu Y-m-d.
- `to_decimal( $value )` (private) — Konwertuje wartosc na float z obsluga przecinka.
- `to_int( $value )` (private) — Konwertuje wartosc na int z zaokragleniem.
- `get_purchase_action_types_priority()` (private) — Zwraca priorytetowa liste typow akcji zakupu do ekstrakcji wartosci konwersji.
- `get_metric_map( $raw )` (private) — Mapuje tablice action_type/value na slownik klucz-wartosc.
- `extract_conversion_value( $row )` (private) — Wyciaga wartosc konwersji z wiersza danych Facebook (z conversion_value lub action_values).
- `extract_roas( $row, $conversion_value, $spend )` (private) — Oblicza ROAS z purchase_roas lub jako conversion_value/spend.
- `get_level_config( $level )` (private) — Zwraca konfiguracje tabel/kolumn dla danego poziomu (campaign/adset/ad).
- `get_clients_for_reports()` — Pobiera klientow z Facebook Ads Account ID do raportow.
- `get_entities_with_latest_metrics( $client_id, $level, $filters )` — Pobiera encje Facebook Ads z najnowszymi metrykami (kampanie, zestawy lub reklamy).
- `get_entity_history( $level, $entity_id, $start, $length, $revert )` — Pobiera stronicowana historie encji Facebook Ads.
- `get_entity_history_total( $level, $entity_id )` — Zwraca laczna liczbe wpisow historii encji Facebook Ads.

### Klasa `\factory\Logs` (`autoload/factory/class.Logs.php`)
- `add( $level, $source, $message, $context, $client_id )` — Dodaje nowy wpis logu z poziomem, zrodlem, wiadomoscia i opcjonalnym kontekstem JSON.
- `get_data( $start, $length, $filters )` — Pobiera stronicowana liste logow z filtrami (level, source, daty) i nazwa klienta.
- `get_records_total( $filters )` — Zwraca laczna liczbe logow spelniajacych podane filtry.
- `get_one( $id )` — Pobiera pojedynczy wpis logu po ID z nazwa klienta.
- `cleanup_old( $days )` — Usuwa logi starsze niz podana liczba dni (domyslnie 30).
- `get_sources()` — Pobiera liste unikalnych zrodel logow.

### Klasa `\factory\Products` (`autoload/factory/class.Products.php`)
- `is_product_core_field( $field )` (private) — Sprawdza czy pole nalezy do zestawu edytowalnych pol produktu.
- `delete_product( $product_id )` — Usuwa produkt po ID.
- `delete_products( $product_ids )` — Usuwa wiele produktow po tablicy ID.
- `get_product_comments( $product_id )` — Pobiera komentarze produktu posortowane od najnowszego.
- `delete_product_comment( $comment_id )` — Usuwa komentarz produktu po ID.
- `get_ad_group_delete_context( $ad_group_id )` — Pobiera kontekst grupy reklam (klient, kampania, external ID) potrzebny do usuwania.
- `delete_ad_group_local( $ad_group_id )` — Oznacza grupe reklam jako wstrzymana (paused) lokalnie.
- `get_product_comment_by_date( $product_id, $date )` — Pobiera komentarz produktu z konkretnej daty.
- `get_scope_alerts( $client_id, $campaign_id, $ad_group_id, $limit )` — Pobiera alerty w kontekscie kampanii/grupy reklam.
- `get_products_without_impressions_30( $client_id, $campaign_id, $ad_group_id, $limit )` — Pobiera produkty bez wyswietlen w ostatnich 30 dniach.
- `get_min_roas( $product_id )` — Zwraca minimalny ROAS ustawiony dla produktu.
- `save_min_roas( $product_id, $min_roas )` — Zapisuje minimalny ROAS dla produktu.
- `build_scope_filters( &$sql, &$params, $campaign_id, $ad_group_id )` (private) — Dodaje filtry kampanii/grupy reklam do zapytania SQL.
- `get_products( $client_id, $search, $limit, $start, $order_name, $order_dir, $campaign_id, $ad_group_id, $custom_label_4 )` — Pobiera stronicowana liste produktow klienta z zagregowanymi statystykami i filtrami.
- `get_roas_bounds( $client_id, $search, $campaign_id, $ad_group_id, $custom_label_4 )` — Zwraca minimalny i maksymalny ROAS wsrod produktow klienta.
- `get_account_conversion_rate( $client_id )` — Oblicza wspolczynnik konwersji konta (conversions / clicks).
- `get_records_total_products( $client_id, $search, $campaign_id, $ad_group_id, $custom_label_4 )` — Zwraca laczna liczbe produktow spelniajacych filtry (do paginacji).
- `get_product_full_context( $product_id )` — Pobiera pelne dane produktu z zagregowanymi statystykami.
- `get_distinct_custom_label_4( $client_id )` — Pobiera unikalne wartosci custom_label_4 dla klienta (do filtrowania).
- `get_product_data( $product_id, $field )` — Pobiera wartosc konkretnego pola produktu (tylko dozwolone pola).
- `get_product_merchant_context( $product_id )` — Pobiera kontekst produktu z ID konta Merchant Center.
- `add_product_merchant_sync_log( $row )` — Dodaje wpis logu synchronizacji produktu z Merchant Center.
- `get_product_merchant_sync_logs( $product_id, $limit )` — Pobiera logi synchronizacji Merchant Center dla produktu.
- `get_product_ads_keyword_context( $product_id )` — Pobiera kontekst produktu z customer_id Google Ads (do Keyword Planner).
- `get_cached_keyword_planner_terms( $product_id, $source_url, $limit )` — Pobiera zcache'owane frazy z Keyword Planner dla produktu i URL.
- `replace_keyword_planner_terms( $product_id, $source_url, $customer_id, $terms )` — Zastepuje zcache'owane frazy Keyword Planner nowymi (delete + insert).
- `set_product_data( $product_id, $field, $value )` — Zapisuje wartosc pola produktu (tylko dozwolone pola, z obsluga product_url).
- `get_product_history( $client_id, $product_id, $start, $limit, $campaign_id, $ad_group_id )` — Pobiera stronicowana historie dzienna produktu (zagregowana).
- `get_records_total_product_history( $client_id, $product_id, $campaign_id, $ad_group_id )` — Zwraca liczbe unikalnych dat w historii produktu (do paginacji).
- `get_product_history_30( $client_id, $product_id, $start, $limit, $campaign_id, $ad_group_id )` — Pobiera 30-dniowa historie produktu (tabela products_history_30).
- `get_impressions_30( $product_id, $campaign_id, $ad_group_id )` — Zwraca sume wyswietlen produktu z ostatnich 30 dni.
- `get_clicks_30( $product_id, $campaign_id, $ad_group_id )` — Zwraca sume klikniec produktu z ostatnich 30 dni.
- `add_product_comment( $product_id, $comment, $date )` — Dodaje lub aktualizuje komentarz produktu na dana date (upsert).
- `get_product_scope_context( $product_id )` — Pobiera kontekst produktu (klient, offer_id, customer_id, merchant_id).
- `get_campaign_scope_context( $campaign_id )` — Pobiera kontekst kampanii (klient, external ID, nazwa).
- `get_ad_group_scope_context( $ad_group_id )` — Pobiera kontekst grupy reklam (kampania, external ID, nazwa).
- `get_next_local_campaign_external_id( $client_id )` (private) — Generuje nastepne ujemne external ID dla lokalnej kampanii.
- `get_next_local_ad_group_external_id( $campaign_id )` (private) — Generuje nastepne ujemne external ID dla lokalnej grupy reklam.
- `create_local_campaign( $client_id, $campaign_name )` — Tworzy lokalna kampanie (z ujemnym external ID) lub zwraca istniejaca.
- `create_local_ad_group( $campaign_id, $ad_group_name )` — Tworzy lokalna grupe reklam (z ujemnym external ID) lub zwraca istniejaca.
- `assign_product_scope( $product_id, $campaign_id, $ad_group_id )` — Przypisuje produkt do kampanii i grupy reklam (tworzac wpis products_aggregate).

### Klasa `\factory\Users` (`autoload/factory/class.Users.php`)
- `user_details( $user_id )` — Pobiera dane uzytkownika po ID z cache'em plikowym.
- `get_default_project( $user_id )` — Zwraca domyslny projekt uzytkownika.
- `get_user_email( $user_id )` — Zwraca adres e-mail uzytkownika.
- `user_name( $user_id )` — Zwraca pelne imie i nazwisko uzytkownika.
- `users_list()` — Pobiera liste wszystkich uzytkownikow.
- `settings_save( $user_id, $pushover_api, $pushover_user )` — Zapisuje ustawienia powiadomien Pushover uzytkownika.
- `login( $email, $password )` — Loguje uzytkownika po e-mailu i hasle, zwraca dane lub false.

---

## Services (`autoload/services/`)

### Klasa `\services\ClaudeApi` (`autoload/services/class.ClaudeApi.php`)
- `is_configured()` — Sprawdza czy klucz API Claude jest ustawiony w bazie.
- `call_api( $system_prompt, $user_prompt, $max_tokens )` (private) — Wysyla zapytanie do Anthropic Messages API i zwraca odpowiedz.
- `build_context_text( $context )` (private) — Buduje tekst kontekstu produktu (nazwa, metryki, tresc strony) do promptu AI.
- `get_prompt_template( $setting_key, $default_template )` (private) — Pobiera customowy szablon promptu z ustawien lub zwraca domyslny.
- `expand_prompt_template( $template, $vars )` (private) — Podstawia zmienne `{{klucz}}` w szablonie promptu.
- `suggest_title( $context )` — Generuje 3 warianty tytulu produktu przez Claude i wybiera najlepszy (z Keyword Planner).
- `suggest_description( $context )` — Generuje opis produktu przez Claude z uwzglednieniem tresci strony i Keyword Planner.
- `suggest_category( $context, $categories )` — Sugeruje kategorie Google Product Taxonomy dla produktu przez Claude.

### Klasa `\services\FacebookAdsApi` (`autoload/services/class.FacebookAdsApi.php`)
- `__construct( $access_token, $api_version )` — Inicjalizuje klienta API z tokenem dostepu i wersja API.
- `is_configured()` — Sprawdza czy token dostepu jest ustawiony.
- `get_api_version()` — Zwraca wersje API Graph.
- `get_setting( $key )` (static) — Pobiera wartosc ustawienia z tabeli settings.
- `set_setting( $key, $value )` (static) — Zapisuje ustawienie (upsert) z obsluga znacznika czasu bledu.
- `normalize_ad_account_id( $account_id )` (static) — Normalizuje ID konta Facebook Ads do formatu `act_XXXX`.
- `fetch_active_insights_last_days( $account_id, $days, $active_only )` — Pobiera statystyki Facebook Ads z ostatnich N dni.
- `fetch_active_insights_for_date( $account_id, $date, $active_only )` — Pobiera statystyki Facebook Ads za konkretna date.
- `fetch_active_insights_for_range( $account_id, $since, $until, $active_only )` — Pobiera statystyki Facebook Ads za zakres dat (zagregowane).
- `fetch_campaigns_all_time( $account_id, $active_only )` — Pobiera statystyki kampanii Facebook za caly czas (date_preset=maximum) z ROAS.
- `fetch_active_insights_range( $account_id, $since, $until, $active_only, $days, $aggregate )` (private) — Pobiera insights na 3 poziomach (campaign/adset/ad) za zakres dat.
- `fetch_all_pages( $url, $params )` (private) — Pobiera wszystkie strony wynikow z paginowanego endpointu Graph API.
- `request_json( $url, $params )` (private) — Wykonuje zapytanie HTTP GET do Graph API i zwraca zdekodowany JSON.

### Klasa `\services\GeminiApi` (`autoload/services/class.GeminiApi.php`)
- `is_configured()` — Sprawdza czy klucz API Gemini jest ustawiony w bazie.
- `call_api( $system_prompt, $user_prompt, $max_tokens, $temperature )` (private) — Wysyla zapytanie do Gemini generateContent API (z obsluga thinking models).
- `build_context_text( $context )` (private) — Buduje tekst kontekstu produktu (nazwa, metryki, tresc strony) do promptu AI.
- `get_prompt_template( $setting_key, $default_template )` (private) — Pobiera customowy szablon promptu z ustawien lub zwraca domyslny.
- `expand_prompt_template( $template, $vars )` (private) — Podstawia zmienne `{{klucz}}` w szablonie promptu.
- `suggest_title( $context )` — Generuje 3 warianty tytulu produktu przez Gemini i wybiera najlepszy (z Keyword Planner).
- `suggest_description( $context )` — Generuje opis produktu przez Gemini z uwzglednieniem tresci strony i Keyword Planner.
- `suggest_category( $context, $categories )` — Sugeruje kategorie Google Product Taxonomy dla produktu przez Gemini.

### Klasa `\services\GoogleAdsApi` (`autoload/services/class.GoogleAdsApi.php`)
- `__construct()` — Inicjalizuje klienta Google Ads/Merchant z tokenami z tabeli settings.
- `get_setting( $key )` (static) — Pobiera wartosc ustawienia z tabeli settings.
- `set_setting( $key, $value )` (static) — Zapisuje ustawienie (upsert) z automatycznym znacznikiem czasu bledu.
- `is_configured()` — Sprawdza czy wymagane dane Google Ads API sa ustawione.
- `is_merchant_configured()` — Sprawdza czy dane do Google Merchant Center API sa ustawione.
- `get_merchant_product_links_for_offer_ids( $merchant_account_id, $offer_ids )` — Pobiera URL-e produktow z Merchant Center dla podanych offer_id.
- `get_merchant_products_for_offer_ids( $merchant_account_id, $offer_ids )` — Pobiera pelne dane produktow z Merchant Center dla podanych offer_id.
- `try_direct_merchant_product_get( $merchant_account_id, $offer_id, $access_token )` (private) — Probuje bezposrednio pobrac produkt z Merchant Center po skonstruowanym productId.
- `update_merchant_product_fields_by_offer_id( $merchant_account_id, $offer_id, $fields )` — Aktualizuje pola produktu w Merchant Center (PATCH) po offer_id.
- `get_access_token()` (private) — Zwraca access token Google Ads (z cache lub odswiezony).
- `refresh_access_token()` (private) — Odswieza access token Google Ads przez OAuth2 refresh.
- `get_merchant_access_token()` (private) — Zwraca access token Merchant Center (z cache lub odswiezony).
- `refresh_merchant_access_token()` (private) — Odswieza access token Merchant Center przez OAuth2 refresh.
- `search_stream( $customer_id, $gaql_query )` — Wykonuje zapytanie GAQL przez Google Ads searchStream i zwraca wyniki.
- `mutate( $customer_id, $mutate_operations, $partial_failure )` — Wykonuje operacje mutacji (create/update/remove) na zasobach Google Ads.
- `normalize_ads_customer_id( $customer_id )` (private) — Usuwa znaki niebedace cyframi z customer ID.
- `parse_resource_id( $resource_name )` (private) — Wyciaga numeryczne ID z resource_name Google Ads.
- `create_standard_shopping_campaign( $customer_id, $merchant_account_id, $campaign_name, $daily_budget, $sales_country )` — Tworzy kampanie Standard Shopping z budzetem w Google Ads.
- `get_listing_groups_count_for_ad_group( $customer_id, $ad_group_id )` (private) — Zwraca liczbe listing groups w grupie reklam.
- `get_listing_group_nodes_for_ad_group( $customer_id, $ad_group_id )` (private) — Pobiera wezly listing group z relacjami rodzic-dziecko.
- `build_listing_group_removal_order( $nodes )` (private) — Buduje kolejnosc usuwania wezlow listing group (liscie najpierw).
- `clear_listing_groups_in_ad_group( $customer_id, $ad_group_id )` (private) — Usuwa wszystkie listing groups z grupy reklam.
- `find_ad_group_id_by_campaign_and_name( $customer_id, $campaign_id, $ad_group_name )` (private) — Wyszukuje ID grupy reklam po kampanii i nazwie.
- `get_ad_group_status( $customer_id, $ad_group_id )` (private) — Pobiera status grupy reklam z Google Ads.
- `enable_ad_group( $customer_id, $ad_group_id )` (private) — Wlacza wstrzymana grupe reklam (PAUSED -> ENABLED).
- `remove_ad_group( $customer_id, $ad_group_id )` — Usuwa grupe reklam w Google Ads (z obsluga NOT_FOUND).
- `get_root_listing_group_resource_name( $customer_id, $ad_group_id )` (private) — Pobiera resource_name korzenia listing group w grupie reklam.
- `extract_first_ad_group_criterion_resource_name_from_mutate( $mutate_response )` (private) — Wyciaga resource_name z odpowiedzi mutate na ad_group_criterion.
- `ensure_standard_shopping_offer_in_ad_group( $customer_id, $ad_group_id, $offer_id, $cpc_bid )` — Ustawia filtr produktu (listing group) w grupie reklam Standard Shopping.
- `create_standard_shopping_ad_group_with_offer( $customer_id, $campaign_id, $ad_group_name, $offer_id, $cpc_bid )` — Tworzy grupe reklam Standard Shopping z reklama i filtrem produktu (obsluguje duplikaty nazw).
- `generate_keyword_ideas_from_url( $customer_id, $url, $limit )` — Generuje propozycje slow kluczowych z Keyword Planner na podstawie URL.
- `add_negative_keyword_to_ad_group( $customer_id, $ad_group_id, $keyword_text, $match_type )` — Dodaje wykluczajace slowo kluczowe do grupy reklam w Google Ads (z weryfikacja i obsluga duplikatow).
- `add_negative_keyword_to_campaign( $customer_id, $campaign_id, $keyword_text, $match_type )` — Dodaje wykluczajace slowo kluczowe do kampanii w Google Ads (z weryfikacja i obsluga duplikatow).
- `remove_negative_keyword_from_campaign( $customer_id, $campaign_id, $keyword_text, $match_type )` — Usuwa wykluczajace slowo kluczowe z kampanii w Google Ads.
- `remove_negative_keyword_from_ad_group( $customer_id, $ad_group_id, $keyword_text, $match_type )` — Usuwa wykluczajace slowo kluczowe z grupy reklam w Google Ads.
- `gaql_escape( $value )` (private) — Escapuje wartosc dla zapytan GAQL (backslash i apostrof).
- `add_keyword_to_ad_group( $customer_id, $ad_group_id, $keyword_text, $match_type )` — Dodaje slowo kluczowe do grupy reklam w Google Ads (z obsluga duplikatow).
- `remove_keyword_from_ad_group( $customer_id, $ad_group_id, $keyword_text, $match_type )` — Usuwa slowo kluczowe z grupy reklam w Google Ads.
- `update_keyword_match_type( $customer_id, $ad_group_id, $keyword_text, $old_match_type, $new_match_type )` — Zmienia typ dopasowania slowa kluczowego (remove + add) w Google Ads.
- `verify_negative_keyword_exists( $customer_id, $scope, $keyword_text, $match_type, $campaign_id, $ad_group_id )` (private) — Weryfikuje przez GAQL czy wykluczajace slowo kluczowe istnieje (z retry).
- `get_products_for_date( $customer_id, $date )` — Pobiera dane produktow Shopping i PMax za konkretna date (z URL-ami z Merchant Center).
- `gaql_field_leaf_to_json_key( $leaf )` (private) — Konwertuje nazwe pola GAQL (snake_case) na klucz JSON (camelCase).
- `is_likely_image_url( $url )` (private) — Sprawdza czy URL prawdopodobnie wskazuje na obrazek.
- `is_valid_merchant_product_url( $url )` (private) — Sprawdza czy URL produktu Merchant jest poprawny (nie obrazek, poprawny format).
- `get_product_urls_by_offer_id( $customer_id, $date )` (private) — Pobiera URL-e produktow z shopping_product (fallback dla brakujacych product_link).
- `get_campaigns_30_days( $customer_id, $as_of_date )` — Pobiera kampanie z metrykami z ostatnich 30 dni (z obliczonym ROAS).
- `get_campaigns_all_time( $customer_id, $as_of_date )` — Pobiera kampanie z metrykami all-time (koszt, wartosc konwersji, ROAS).
- `get_ad_groups_30_days( $customer_id, $as_of_date )` — Pobiera grupy reklam z metrykami z ostatnich 30 dni.
- `get_ad_groups_all_time( $customer_id, $as_of_date )` — Pobiera grupy reklam z metrykami all-time.
- `get_shopping_ad_group_offer_ids( $customer_id )` — Pobiera offer_id przypisane do grup reklam Shopping (z listing groups, kilka wariantow zapytan).
- `get_shopping_ad_group_offer_ids_from_shopping_product( $customer_id )` — Pobiera offer_id z shopping_product dla grup reklam Shopping (ostatnie 30 dni).
- `get_shopping_ad_group_offer_ids_from_performance( $customer_id )` — Pobiera offer_id z shopping_performance_view dla grup reklam Shopping.
- `get_search_terms_30_days( $customer_id )` — Pobiera frazy wyszukiwane z ostatnich 30 dni (Shopping + PMax).
- `get_search_terms_all_time( $customer_id )` — Pobiera frazy wyszukiwane all-time (Shopping + PMax).
- `get_ad_keywords_30_days( $customer_id )` — Pobiera slowa kluczowe kampanii Search z metrykami z ostatnich 30 dni.
- `get_ad_keywords_all_time( $customer_id )` — Pobiera slowa kluczowe kampanii Search z metrykami all-time.
- `get_pmax_search_terms_30_days( $customer_id )` (private) — Pobiera frazy wyszukiwane PMax z ostatnich 30 dni.
- `get_pmax_search_terms_all_time( $customer_id )` (private) — Pobiera frazy wyszukiwane PMax all-time.
- `get_search_terms_for_date( $customer_id, $date )` — Pobiera frazy wyszukiwane za konkretna date (Shopping + PMax).
- `get_pmax_search_terms_for_date( $customer_id, $date )` (private) — Pobiera frazy wyszukiwane PMax za konkretna date.
- `get_negative_keywords( $customer_id )` — Pobiera wszystkie wykluczajace slowa kluczowe konta (campaign + ad_group scope).
- `aggregate_ad_groups( $results )` (private) — Agreguje surowe wyniki GAQL grup reklam (sumuje metryki, oblicza ROAS).
- `aggregate_search_terms( $results )` (private) — Agreguje surowe wyniki GAQL fraz wyszukiwanych (sumuje metryki, oblicza ROAS).
- `aggregate_campaign_search_terms( $results )` (private) — Agreguje surowe wyniki GAQL fraz wyszukiwanych na poziomie kampanii (PMax).
- `aggregate_ad_keywords( $results )` (private) — Agreguje surowe wyniki GAQL slow kluczowych (sumuje metryki, oblicza ROAS).

### Klasa `\services\OpenAiApi` (`autoload/services/class.OpenAiApi.php`)
- `is_configured()` — Sprawdza czy klucz API OpenAI jest ustawiony w bazie.
- `fetch_page_content( $url )` — Pobiera i oczyszcza zawartosc strony produktu (HTML -> tekst, max 1800 znakow).
- `clean_page_content_text( $text )` (private) — Czysci tekst strony z szumu (cookies, nawigacja, duplikaty).
- `call_api( $system_prompt, $user_prompt, $max_tokens, $temperature, $extra_payload )` (private) — Wysyla zapytanie do OpenAI Chat Completions API (z obsluga GPT-5).
- `build_context_text( $context )` (private) — Buduje tekst kontekstu produktu (nazwa, metryki, tresc strony) do promptu AI.
- `get_prompt_template( $setting_key, $default_template )` (private) — Pobiera customowy szablon promptu z ustawien lub zwraca domyslny.
- `expand_prompt_template( $template, $vars )` (private) — Podstawia zmienne `{{klucz}}` w szablonie promptu.
- `extract_meaningful_tokens( $text )` (private) — Wyciaga znaczace tokeny z tekstu (bez stopwords, min 4 znaki).
- `select_relevant_keyword_terms( $terms, $context, $limit )` (private) — Wybiera najlepiej pasujace frazy Keyword Planner do kontekstu produktu (scoring overlap).
- `build_keyword_planner_text( $context, $usage_line, $limit )` (private) — Buduje sekcje tekstu z frazami Keyword Planner do promptu.
- `parse_title_candidates( $raw )` (static) — Parsuje odpowiedz AI z wariantami tytulow (JSON lub linie tekstu).
- `score_title_candidate( $title, $context )` (private) — Oblicza wynik jakosci kandydata na tytul (dlugosc, bad words, overlap, wzbogacenie).
- `pick_best_title_candidate( $candidates, $context )` (static) — Wybiera najlepszy tytul z kandydatow na podstawie scoringu.
- `get_default_title_prompt_template()` (static) — Zwraca domyslny szablon promptu do generowania tytulow produktow.
- `get_default_description_prompt_template()` (static) — Zwraca domyslny szablon promptu do generowania opisow produktow.
- `suggest_title( $context )` — Generuje 3 warianty tytulu produktu przez OpenAI i wybiera najlepszy (z Keyword Planner).
- `suggest_description( $context )` — Generuje opis produktu przez OpenAI z uwzglednieniem tresci strony i Keyword Planner.
- `suggest_category( $context, $categories )` — Sugeruje kategorie Google Product Taxonomy dla produktu przez OpenAI.
- `suggest_negative_keywords_to_exclude( $search_terms_rows, $analysis_context )` — Analizuje frazy wyszukiwane AI i rekomenduje wykluczenia (structured output JSON schema).

---

## View (`autoload/view/`)

### Klasa `\view\Clients` (`autoload/view/class.Clients.php`)
- `main_view( $clients )` — Renderuje glowny widok listy klientow.

### Klasa `\view\Cron` (`autoload/view/class.Cron.php`)
- `main_view()` — Renderuje glowny widok panelu crona.

### Klasa `\view\Logs` (`autoload/view/class.Logs.php`)
- `main_view( $sources )` — Renderuje glowny widok logow z lista zrodel do filtrowania.

### Klasa `\view\Site` (`autoload/view/class.Site.php`)
- `show()` — Renderuje glowny layout strony (zalogowany z menu i alertami lub niezalogowany).

### Klasa `\view\Users` (`autoload/view/class.Users.php`)
- `points_history( $user )` — Renderuje widok historii punktow uzytkownika.
- `settings( $user, $cron_data )` — Renderuje widok ustawien uzytkownika z danymi crona.