update

.paul/codebase/integrations.md

@@ -0,0 +1,80 @@
+# External Integrations
+
+All API credentials are stored in the `settings` DB table and read via `\services\GoogleAdsApi::get_setting($key)` (used globally despite the name).
+
+## Google Ads REST API
+
+- **File:** [autoload/services/class.GoogleAdsApi.php](autoload/services/class.GoogleAdsApi.php) (~3,200 lines)
+- **API version:** `v23` (constant `$API_VERSION = 'v23'`)
+- **Base URLs:**
+  - Ads: `https://googleads.googleapis.com`
+  - Merchant Center: `https://shoppingcontent.googleapis.com/content/v2.1`
+  - OAuth: `https://oauth2.googleapis.com/token`
+- **Auth:** OAuth 2.0 refresh-token flow. Settings keys: `google_ads_developer_token`, `google_ads_client_id`, `google_ads_client_secret`, `google_ads_refresh_token`, `google_ads_manager_account_id`. Merchant variant: `google_merchant_refresh_token` (falls back to ads token).
+- **Endpoints used:**
+  - `POST /v23/customers/{customerId}/googleAds:search` — campaigns, search terms, ad groups
+  - `GET /content/v2.1/{merchantAccountId}/products` — product listing/details
+  - Product ID format: `online:{lang}:{feedLabel}:{offerId}`
+- **Errors:** stored in settings keys `google_ads_last_error` / `google_ads_last_error_at`.
+- **Cron:** `/cron/cron_universal`, `/cron/cron_products_urls`, `/cron/cron_campaigns_product_alerts_merchant`.
+
+## Facebook Ads Graph API
+
+- **File:** [autoload/services/class.FacebookAdsApi.php](autoload/services/class.FacebookAdsApi.php) (~300 lines)
+- **API version:** `v25.0` (default, configurable per client)
+- **Base URL:** `https://graph.facebook.com/{version}/{accountId}/insights`
+- **Auth:** access token in `facebook_ads_access_token` setting.
+- **Methods:** `get_insights()`, `get_campaigns()`, `parse_date_range()`. 30-day rolling window.
+- **Errors:** `facebook_ads_last_error` / `_at`.
+- **Cron:** `/cron/cron_facebook_ads`.
+
+## Google Merchant Center
+
+Integrated through `GoogleAdsApi`. Supplemental TSV feeds generated via [autoload/services/class.SupplementalFeed.php](autoload/services/class.SupplementalFeed.php) into `feeds/supplemental_{client_id}.tsv`. XML feed parsing via [autoload/services/class.XmlFeedImporter.php](autoload/services/class.XmlFeedImporter.php) using `\Chunk` streaming reader.
+
+## OpenAI
+
+- **File:** [autoload/services/class.OpenAiApi.php](autoload/services/class.OpenAiApi.php) (~400 lines)
+- **Endpoint:** `https://api.openai.com/v1/chat/completions`
+- **Auth:** Bearer token in `openai_api_key` setting; model in `openai_model`.
+- **Use cases:** product title (≤150 chars) and description (≤5000 chars) generation, page-content fetch + HTML strip + LLM rewrite. System prompt: Polish-language Merchant Center best practices.
+
+## Claude (Anthropic)
+
+- **File:** [autoload/services/class.ClaudeApi.php](autoload/services/class.ClaudeApi.php) (~300 lines)
+- **Endpoint:** `https://api.anthropic.com/v1/messages`
+- **Default model:** `claude-sonnet-4-5-20250929` (override via `claude_model`)
+- **Auth:** `x-api-key` header from `claude_api_key`. `anthropic-version: 2023-06-01`.
+- **Use cases:** same as OpenAI (product text optimization).
+
+## Google Gemini
+
+- **File:** [autoload/services/class.GeminiApi.php](autoload/services/class.GeminiApi.php) (~400 lines)
+- **Base:** `https://generativelanguage.googleapis.com/v1beta/models/`
+- **Default model:** `gemini-2.5-flash` (override via `gemini_model`)
+- **Auth:** API key in `?key=` query param (`gemini_api_key`).
+- **Special handling:** detects `gemini-2.5*` as thinking models — multiplies max_tokens by 6 for internal reasoning. Uses `systemInstruction` field.
+
+## SMTP (PHPMailer)
+
+- **Library:** [libraries/phpmailer/](libraries/phpmailer/) (3 files)
+- **Wrapper:** `\S::send_email($email, $subject, $text, $file)` in [autoload/class.S.php](autoload/class.S.php)
+- **Config (from [config.php](config.php)):** host `mail.project-pro.pl`, port 25, login `www@project-pro.pl`, password in plaintext (see [concerns.md](concerns.md)). SSL/TLS verification disabled (self-signed cert support). UTF-8, HTML body. Default From `www@projectpro.pl`, Reply-To `biuro@project-pro.pl`.
+
+## Other / minor
+
+- **Allegro.pl** — [autoload/controls/class.Allegro.php](autoload/controls/class.Allegro.php) (legacy marketplace integration)
+- **Open Page Rank API** — referenced in [api.php](api.php) for domain authority lookups
+- **Domain tester** — third-party domain validation in [api.php](api.php)
+
+## Summary
+
+| Integration | API ver | Auth | Cron |
+|---|---|---|---|
+| Google Ads | v23 | OAuth 2.0 refresh | `/cron/cron_universal` |
+| Google Merchant | v2.1 | OAuth 2.0 | `/cron/cron_campaigns_product_alerts_merchant` |
+| Facebook Ads | v25.0 | Bearer token | `/cron/cron_facebook_ads` |
+| OpenAI | latest | API key (header) | on-demand |
+| Claude | v1 / 2023-06-01 | `x-api-key` | on-demand |
+| Gemini | v1beta | API key (query) | on-demand |
+| SMTP | — | Basic auth | reminders via `cron.php` |