Initial commit

README.md

@@ -0,0 +1,153 @@
+# iklim.co Python sandbox istemcileri
+
+Bu klasör HMAC imzalı istek, otomatik login/refresh ve `.env` token saklama
+özelliklerini ortak bir istemci katmanında toplar. Geo alarm registration istemcisi
+bu ortak yapıyı kullanarak noktalı virgüllü CSV satırlarını sırayla işler.
+
+## Dosyalar
+
+- `common/`: tekrar kullanılabilir API, HMAC, retry ve authentication katmanı
+- `login.py`: manuel login komutu
+- `nowcast-geo-register.py`: CSV geo alarm registration istemcisi
+- `.env.example`: güvenli ortam değişkeni şablonu
+- `webhook.example.json`: dört webhook authentication seçeneğini içeren şablon
+- `nowcast-geo-alarm-filter.example.json`: ortak nowcast geo alarm filtreleri şablonu
+- `nowcast-geo-alarm-registrations.example.csv`: CSV şablonu
+
+Gerçek değerler için `.env`, `webhook.json` ve
+`nowcast-geo-alarm-filter.json` kullanılır. `.env` ile `webhook.json` kaynak kod
+deposuna eklenmemelidir.
+
+## Kurulum
+
+```bash
+cd iklim-sandbox
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -r requirements.txt
+```
+
+Yeni kurulumda şablonları kopyalayın ve gerçek değerlerle düzenleyin:
+
+```bash
+cp .env.example .env
+cp webhook.example.json webhook.json
+cp nowcast-geo-alarm-filter.example.json nowcast-geo-alarm-filter.json
+cp nowcast-geo-alarm-registrations.example.csv nowcast-geo-alarm-registrations.csv
+```
+
+## CSV biçimi
+
+Girdi UTF-8 ve noktalı virgül ayracına sahip olmalıdır:
+
+```csv
+city;district;recipientId
+Ankara;Çankaya;recipient-001
+İstanbul;Kadıköy;recipient-002
+```
+
+Script aynı dosyaya şu üç sonuç sütununu ekler veya mevcut değerlerini günceller:
+
+```csv
+city;district;recipientId;status;httpStatus;registrationId
+Ankara;Çankaya;recipient-001;SUCCESS;HTTP_200;f7587d9e-2481-4b4c-818d-c8d1946851b7
+```
+
+- İl ve ilçe adları trim edilip Türkçe büyük/küçük harf kurallarıyla kesin eşleştirilir.
+- Bulunamayan konumlar `FAILED;NOT_SENT;` olarak kaydedilir.
+- Daha önce `SUCCESS` olmuş satırlar konsola bilgi yazılarak atlanır.
+- Her satırdan sonra CSV aynı dizinde geçici dosyayla atomik olarak güncellenir.
+- `recipientId` boş olamaz ve US-ASCII karakterlerinden oluşmalıdır.
+
+## İl ve ilçe sorgu cache'i
+
+Şehir listesi her script çalıştırmasında yalnızca bir kez API'den alınır ve isim-ID
+eşleştirmesi bellekte tutulur. İlçe listesi de her benzersiz şehir için yalnızca ilk
+karşılaşmada alınır; aynı şehirdeki sonraki CSV satırlarında bellekteki sonuç
+kullanılır. Cache diske yazılmaz ve script kapandığında temizlenir.
+
+## Webhook yapılandırması
+
+`webhook.json` içindeki `authentication.selected` şu değerlerden biri olmalıdır:
+
+- `BASIC`
+- `JWT_TOKEN`
+- `API_KEY`
+- `HMAC_SIGNATURE`
+
+Yalnızca seçilen seçeneğin `options` altındaki alanları API'ye gönderilir. İlk
+initialization isteğinde tam webhook config gönderilir ve `accountId` kesinlikle
+gönderilmez. İlk başarılı kayıttan sonra `.env` içindeki
+`IKLIM_WEBHOOK_INITIALIZED=true` yapılır. Sonraki kayıtlar webhook altında yalnızca
+API'nin `/v1/users/me` yanıtındaki `account.id` değerini gönderir. Webhook'u yeniden
+tanımlamak için bu değeri elle `false` yapın.
+
+Test/prod ortamını veya kullanıcı hesabını değiştirirken de yeni ortamın webhook'u
+ilk kayıtla tanımlayabilmesi için `IKLIM_WEBHOOK_INITIALIZED=false` yapın.
+
+## Nowcast geo alarm filter yapılandırması
+
+Tüm CSV satırlarına uygulanacak ortak nowcast filtreleri
+`nowcast-geo-alarm-filter.json` içinde tutulur. Yıldırım, thunderstorm ve yağış
+filtrelerinden ihtiyaç duyulmayan nesneler dosyadan çıkarılabilir. API isteğindeki
+alan adı doküman gereği yine `filter` olarak gönderilir.
+
+## Otomatik authentication
+
+Ortak istemci her yetkili istekten önce access token'ı kontrol eder:
+
+1. Access token yoksa `.env` kullanıcı bilgileriyle login olur.
+2. Access token'ın bitmesine 60 saniyeden az kaldıysa geçerli refresh token ile yeniler.
+3. Refresh token yoksa/geçersizse yeniden login olur.
+4. Sunucu `401` döndürürse refresh veya login yapıp isteği bir kez daha gönderir.
+5. Yeni tokenları ve JWT `exp` değerlerini `.env` dosyasına kaydeder.
+
+Yetkili isteklerde `Authorization: Bearer <accessToken>` ile HMAC başlıkları birlikte
+gönderilir. Tokenlar ve parolalar konsola yazılmaz.
+
+## Retry davranışı
+
+Ağ hataları ile `429`, `500`, `502`, `503` ve `504` yanıtları ilk istekten sonra en
+fazla üç kez, varsayılan olarak 2, 4 ve 8 saniye beklenerek tekrar edilir. `429`
+yanıtındaki `Retry-After` varsa ona uyulur. Bir operasyonun retry isteklerinde aynı
+idempotency key; yeni timestamp, nonce ve HMAC imzası kullanılır.
+
+Belirsiz sonuç veya `409` sonrasında kayıt `recipientId` ile sorgulanır. Kayıt
+bulunursa `registrationId` kurtarılır ve satır `SUCCESS` yapılır.
+
+## Debug HTTP logları
+
+Her çalıştırmada maskelenmiş HTTP istek ve yanıtları aşağıdaki dosyaya yazılır:
+
+```text
+logs/iklim-api-debug.log
+```
+
+Log; istek metodu, URL, deneme numarası, başlıklar, istek gövdesi, HTTP durum kodu,
+yanıt başlıkları ve yanıt gövdesini içerir. Parola, kullanıcı adı, JWT, refresh
+token, API key, webhook secret, `Authorization`, cookie ve `X-Signature` değerleri
+maskelenir. Dosya 5 MB'a ulaştığında döndürülür ve en fazla üç eski dosya tutulur.
+Başarılı API yanıtındaki `warning`/`warnings` alanları ayrıca konsola yazılır.
+
+## Çalıştırma
+
+Manuel login:
+
+```bash
+python login.py
+```
+
+CSV registration:
+
+```bash
+python nowcast-geo-register.py nowcast-geo-alarm-registrations.csv
+```
+
+Farklı config dosyaları vermek için:
+
+```bash
+python nowcast-geo-register.py nowcast-geo-alarm-registrations.csv \
+  --webhook-config another-webhook.json \
+  --nowcast-filter-config another-nowcast-geo-alarm-filter.json \
+  --debug-log logs/custom-debug.log
+```