Packages/RbnApi — dış servis kapısı (API sağlayıcıları + servisler)

Doğrulanan kod tabanı: d49b4413 (dal feat/fw-license-master) · Tarih: 2026-10-05 · Yayın: 0.9.7 = bu commit + sonrası; belge yalnız doğrulama anındaki kodu anlatır
Kaynak klasör: Packages/RbnApi/ — 27 *.php
(1 kök + Managers/ 3 + Models/ 3 + Providers/ 10 + Services/ 10).
Envanter: 27 dosyanın 27'si aşağıda anlatıldı.
Kardeş belgeler: PackageData.md (paket kayıt haritası),
RbnEmail.md, RbnFile.md,
RbnPipeline.md, RbnUtility.md.

1. Ne işe yarar, kim kullanır

Tüm dış servis çağrılarının tek katmanıdır. Üç katman vardır ve
her katman tek yönlü çağrılır:

Controllers / Tasks / Services
  → RbnApi\Services\*        (yüksek seviye, iş bilgisi taşır)
     → RbnApi\Providers\*    (düşük seviye HTTP + URL + anahtar)
        → ApiManager::resolveApiKey()  (anahtar çözümü)
           → RemoteRequest (Core/Http/RemoteRequest.php) → cURL

Kimler çağırır: Packages/PackageData.php:24, 100-110 bunları
services.* ve providers.* anahtarlarıyla kaydeder; herhangi bir controller
$this->service('telegram'), $this->manager('api') gibi adlarla erişir.
Packages/RbnPipeline sosyal paylaşımda doğrudan
FacebookService/InstagramService çağırır
(RbnPipeline/Services/AutoTaskManager.php:457, 491).

2. Klasör/dosya envanteri (27/27)

2.1 Kök (1)

Dosya	Görev	Önemli public yöntemler
`ApiService.php`	Birleşik API geçidi (`app.gemini` / `app.google` tipi servisler).	`gemini(string $type, string $task, array $context = [])`, `google(string $type, array $params = [], ?string $projectKey = null)`

2.2 `Managers/` (3)

Dosya	Görev	Önemli public yöntemler
`Managers/ApiManager.php`	Anahtar çözümleme ve API loglama. `#[Component(alias:'api', type:'manager')]`.	`resolveApiKey(string $apiName, ?string $projectKey = null, array $context = []): string\\|array\\|null`, `resolveApiKeyType(...)`, `log(string $service, string $level, string $message, array $context = [], ?string $projectKey = null)`, `getFlattenedKeys()`, `getLabelForKey(string $key)`
`Managers/AiUsageManager.php`	AI kullanım kaydı, maliyet hesabı ve rapor.	`recordUsage(string $model, array $usageMetadata, ?string $projectKey = null, ?string $taskKey = null, string $requestType = 'text')`, `calculateCost(string $model, int $promptTokens, int $outputTokens)`, `getCurrencyRates()`, `getFilteredReport(array $filters = [], int $page = 1, int $perPage = 20)`, `clearLogs(?string $projectKey = null)`
`Managers/GeminiAppManager.php`	Merkezî AI orkestratörü: proje anahtarı, modül, prompt handler, persona birleştirme, yanıt biçimleme.	`generateText(string $typeOrTitle, string\\|array $titleOrContext = '', array $context = [])`, `generateImage(string $topic, ?string $projectKey = null, bool\\|string $save = false, array $extraContext = [])`; protected: `runTaskOrchestration(...)` `:137`, `parseTextArgs(...)` `:202`, `prepareContext(...)` `:219`, `resolvePromptModule(...)` `:236`

2.3 `Models/` (3)

Dosya	Görev	Önemli public yöntemler
`Models/ApiKeysRegistry.php`	Anahtar beyaz listesi: API adı → ayar anahtarı adı; ücretli anahtar listesi.	`const MAP` (`:16-48`), `const PAID_KEYS` (`:53-57`), `static isPaidKey(string $apiName): bool` (`:62`)
`Models/AiData.php`	Gemini model/fiyat/kabiliyet sözlüğü (`const MODELS`, `:17`).	`get(string $model)`, `getPricing(string $model)`, `getByProvider(string $provider = 'google')`, `getPricingMap()`
`Models/OpenAiPricingRegistry.php`	OpenAI GPT model fiyat referansı (yalnız sabitler).	—

2.4 `Providers/` (10)

Dosya	Görev	Önemli public yöntemler
`Providers/GeminiProvider.php`	Google Gemini AI bağlantı düğümü; `RemoteRequest` üzerinden çağrır.	`call(string $model, array $payload, bool $isImage = false, ?string $projectKey = null, array $context = [])`
`Providers/GoogleMapsProvider.php`	Google Places API iş yeri detayı.	`getPlaceDetails(string $placeId, string $referer, ?string $projectKey = null)`
`Providers/GoogleAnalyticsProvider.php`	GA4 Data API; servis hesabı JSON'u ile token üretir.	`getPropertyId(string $projectKey)`, `isActive(string $projectKey)`, `getServiceAccountConfig(string $projectKey)`, `getReports(string $projectKey, ?string $startDate = null, ?string $endDate = null)`, `getTurkeyCityReports(...)`
`Providers/FacebookProvider.php`	Meta Facebook Graph API çağrı düğümü.	`call(string $method, array $params = [], string $httpMethod = 'GET', ?string $projectKey = null)`
`Providers/InstagramProvider.php`	Meta Graph API çağrı düğümü.	`call(string $method, array $params = [], string $httpMethod = 'GET', ?string $projectKey = null)`
`Providers/TwitterProvider.php`	X/Twitter API çağrı düğümü.	`call(string $method, array $params = [], string $httpMethod = 'POST', bool $isUpload = false, ?string $projectKey = null)`
`Providers/YoutubeProvider.php`	YouTube Data API v3 çağrı düğümü.	`call(string $endpoint, array $params = [], ?string $projectKey = null)`, `getVideo(...)`, `getChannel(...)`, `getPlaylistItems(...)`, `getLiveStreams(...)`, `getPopularVideos(...)`
`Providers/ShopierProvider.php`	Shopier REST çağrı düğümü.	`call(string $method, array $params = [], string $httpMethod = 'GET', ?string $projectKey = null)`
`Providers/TmdbProvider.php`	TMDB çağrı düğümü ve kısayolları.	`call(string $endpoint, array $params = [], ?string $projectKey = null)`, `search(...)`, `getMovie(...)`, `getSeries(...)`, `getPopular(...)`, `getPerson(...)`, `discoverTmdb(...)`
`Providers/TelegramProvider.php`	Telegram Bot API düğümü: token/username/webhook secret `z_settings_api` üzerinden `SettingsApiRepository` ile okunur (`:124,146,162,269`); `secret_token` `hash_equals` ile doğrulanır.	`botToken()`, `botUsername()`, `apiBase()`, `isBotConfigured()`, `isValidChatId(...)`, `isValidStartCode(...)`, `generateStartCode()`, `parseStartCode(...)`, `buildStartLink(...)`, `webhookSecret(bool $persist = true)`, `verifyWebhookSecret(string $given)`, `call(...)`, `sendMessage(...)`, `setWebhook(...)`, `getWebhookInfo()`, `deleteWebhook()`, `getMe()`, `sanitizeText(...)`, `escape(...)`, `cleanDescription(...)`

2.5 `Services/` (10)

Dosya	Görev	Önemli public yöntemler
`Services/GeminiService.php`	Gemini yüksek seviye arayüzü (`@property GeminiProvider $gemini`).	`call(...)`, `ask(string $prompt, ?string $model = null, ?string $projectKey = null, array $context = [])`, `askImage(...)`
`Services/GoogleService.php`	Google iş yeri + Analytics yüksek seviye arayüzü.	`syncBusinessProfile(string $projectKey, bool $apply)` (Google işletme profilini okuyup saat/konum/puan ayarlarını DB'ye yazar; yalnız zamanlayıcı ve `rbn google:sync` çağırır, sayfa isteği çağırmaz), `isAnalyticsActive(?string $projectKey = null)`, `getAnalyticsReport(?string $projectKey = null, ?string $startDate = null, ?string $endDate = null, string $type = 'standard')`
`Services/FacebookService.php`	Sayfa yayınlama ve işlemler.	`call(...)`, `getPageInfo(string $pageId = 'me', array $fields = [...], ?string $projectKey = null)`, `postFeed(string $pageId, string $message, ?string $link = null, ?string $projectKey = null)`, `postPhoto(string $pageId, string $imageUrl, string $caption = '', ?string $projectKey = null)`
`Services/InstagramService.php`	Medya konteyneri + yayın akışı.	`call(...)`, `getProfile(...)`, `createMediaContainer(...)`, `publishMedia(...)`, `publishPhoto(...)`
`Services/TwitterService.php`	X gönderi paylaşımı.	`call(...)`, `send(string $text, ?string $imagePath = null, ?string $projectKey = null)`, `shareContent(string $title, string $url, ?string $imagePath = null, string $suffix = '', ?string $projectKey = null)`
`Services/YoutubeService.php`	Video/kanal/oynatma listesi okuma.	`call(...)`, `getVideo(...)`, `getChannel(...)`, `getPlaylistItems(...)`, `getLiveStreams(...)`, `getPopularVideos(...)`
`Services/TmdbService.php`	TMDB yüksek seviye + fragman URL çıkarma.	`call(...)`, `search(...)`, `getMovie(...)`, `getSeries(...)`, `getPopular(...)`, `extractTrailerUrl(array $videos)`, `getPerson(...)`, `discoverTmdb(...)`
`Services/ShopierService.php`	Ödeme bağlantısı üretimi ve sipariş doğrulama.	`generatePaymentUrl(string $orderNo, string $productName, float $totalPrice, ?string $imageUrl = null, ?string $projectKey = null)`, `verifyOrderOnline(string $productId, ?string $projectKey = null)`
`Services/TelegramService.php`	Telegram bot geçidi; proje bağımsız kısım (olay kuralları, cooldown, `telegram_state` projede kalır).	`botToken()`, `botUsername()`, `apiBase()`, `isBotConfigured()`, `isValidChatId(...)`, `isValidStartCode(...)`, `generateStartCode()`, `parseStartCode(...)`, `buildStartLink(...)`, `webhookSecret(bool $persist = true)`, `verifyWebhookSecret(...)`, `sendMessage(...)`, `setWebhook(...)`, `getWebhookInfo()`, `deleteWebhook()`, `getMe()`, `call(...)`, `sanitizeText(...)`, `escape(...)`, `cleanDescription(...)`
`Services/IndexNowService.php`	Arama motoru IndexNow bildirimi (doğrulama dosyası yazar).	`ping(string $domain, string $projectKey, array $urls)`, `getStats(string $projectKey, int $urlsCount)`, `pingAll(...)`, `pingSingleUrl(string $projectKey, string $path)`

Kapsama: 27/27.

3. Akış

3.1 API anahtarı çözümleme (ücretsiz / ücretli ayrımı)

Provider::call(...)
 └─ ApiManager::resolveApiKey('gemini', $projectKey)        ApiManager.php:21
     ├─ ApiKeysRegistry::MAP['gemini'] → 'GEMINI_API_KEY'   :24
     ├─ resolveApiKeyType() → 'free' | 'paid'              :32
     ├─ FREE  → önce proje önbelleği: api_keys['GEMINI_API_KEY_FREE']   :36-41
     │        → yoksa Master DB: key_type='free' AND is_active=1       :45-51
     └─ PAID  → SIFIR DB SORGUSU, yalnız project_data('api_keys')      :57-60
                (dizi tipindeki anahtarlar alan alan çözülür :61-70)

3.2 Gemini metin üretimi

$geminiApp->generateText($type, $title, $context)
 └─ GeminiAppManager::generateText()        GeminiAppManager.php:?
     ├─ parseTextArgs()   → geri uyumlu (title,type) imzası    :202
     ├─ prepareContext()  → proje/modül/persona birleştirme     :219
     ├─ resolvePromptModule() → taskMap + kural listesi         :236
     └─ runTaskOrchestration() → GeminiService::call()
         └─ GeminiProvider::call()
             ├─ ApiManager::resolveApiKey('gemini')
             └─ $this->remote->post(...)  (Core/Http/RemoteRequest.php)

3.3 IndexNow bildirimi

IndexNowService::ping($domain, $projectKey, $urls)   IndexNowService.php:24
 ├─ url listesi boşsa → hata döner                        :28-30
 ├─ extractDomain() ile host temizlenir (port/şema atılır)  :34
 ├─ is_local() ise ping YAPILMAZ, success döner            :37-40
 ├─ hashToken($projectKey.'_indexnow') → deterministik anahtar  :43
 ├─ public köke "<key>.txt" doğrulama dosyası yazılır        :46-53
 └─ POST https://api.indexnow.org/indexnow                  :56-64
     {host, key, keyLocation, urlList}

3.4 Sosyal paylaşım (RbnPipeline'dan)

AutoTaskManager::dispatchSocialShares()      RbnPipeline/Services/AutoTaskManager.php:386
 ├─ caption birleştirme (özet + hashtag + URL)                :433
 ├─ FacebookService::postFeed(pageId, caption, url)           :457
 └─ InstagramService::publishPhoto(accountId, imageUrl, caption)  :491

4. Yapılandırma / ayar anahtarları

Anahtar	Yer	Varsayılan / not
`ApiKeysRegistry::MAP`	`Models/ApiKeysRegistry.php:16`	Beyaz liste. Listede olmayan API adı `resolveApiKey()`'dan `null` döner (`ApiManager.php:24`) — yani isimsiz anahtar reddedilir, tahmin edilmez.
`ApiKeysRegistry::PAID_KEYS`	`:53-57`	`gemini`, `google`, `openai`. Bu listedekiler sıfır DB sorgusu ile proje önbelleğinden okunur (`ApiManager.php:57`)
`project_data('api_keys')`	`ApiManager.php:37, 58`	Proje keşif önbelleği; `*_FREE` anahtarları yalnız `free` dalında aranır
`z_settings_api`	`Providers/TelegramProvider.php:124,146,162,269`	Telegram token/username/webhook secret tek kaynağı (`SettingsApiRepository`)
`is_local()`	`Services/IndexNowService.php:37`	Yerelde ping atlanır (dış ağa çıkmaz)

5. Tuzaklar ve kurallar

Anahtar sızdırmama kuralı: Telegram token'ı botToken() dışına
çıkmaz; yalnız call() içinde URL'e girer, hiçbir loga/yazmaya yazılmaz
(TelegramProvider.php sınıf dokümanı). Token yoksa fail-closed:
sahte "gonderdim" dönmez.
Katman ayrımı kuralı: iş kuralı (hangi olay kime gider, cooldown,
telegram_state) RbnApi'de yoktur; proje kendi servisinde yazar
(TelegramService sınıf dokümanı, "KAPSAM DIŞI" listesi).
Beyaz liste dışı API reddi sessiz değildir ama da hata değildir:
resolveApiKey() null döner, çağıran kendi hatasını üretir.
IndexNow yerelde sessizce atlar ve success döner — log'dan
ayrılırsa "kaç kez pingledi" sayacı yanıltır (IndexNowService.php:37).
recordUsage() maliyet için AiData/OpenAiPricingRegistry fiyat
haritasını kullanır; model bilinmiyorsa calculateCost() para birimi
bilgisi olmadan çalışır (getCurrencyRates() ayrıdır).
Google Analytics sağlayıcı kimlik bilgisi JSON ile gelir
(getServiceAccountConfig(), :57); bu değer proje ayarındadır, koda
gömülü değildir.

6. Örnek (gerçek koddan)

// Telegram mesajı (proje bağımsız kısım)
$telegram = $this->service('telegram');
$code = $telegram->generateStartCode();
$link = $telegram->buildStartLink($code);
$telegram->sendMessage($chatId, $text);

// API anahtarı çözümleme (doğrudan)
$key = $this->manager('api')->resolveApiKey('gemini', $projectKey);

7. İlgili belgeler

PackageData.md — services.* / managers.* / providers.* kayıt haritası
RbnPipeline.md — bu servisleri tüketen otomasyon hattı
../Core/Http/README.md — RemoteRequest (tüm dış çağrıların taşıyıcısı)
../Core/Http/Security.md — dışarıdan gelen trafiğin koruması (bu paket dışarıya giden trafiği yönetir)
../Core/System/Config.md — project_data() ve ayar önceliği
../kavramlar/02-yapilandirma.md