adsPRO/docs/class-methods.md

adsPRO — Lista klas i metod

Spis tresci

• Klasy bazowe (autoload/)
• Kontrolery (autoload/controls/)
• Factory (autoload/factory/)
• Services (autoload/services/)
• View (autoload/view/)

---

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.