From 8d45cddcedd46ad2044e3cccde0ac0f3e1a05368 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Murat=20=C3=96ZDEM=C4=B0R?= <muratozdemir@tarla.io>
Date: Fri, 23 Oct 2026 19:34:58 +0300
Subject: [PATCH] docs: add usage examples for every point alarm client

---
 README.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/README.md b/README.md
index 7fa7356..46d9e6c 100644
--- a/README.md
+++ b/README.md
@@ -190,14 +190,55 @@ python3 nowcast-point-page.py --polygon "32.8,39.9;32.9,39.9;32.9,40.0;32.8,39.9
 
 ### get
 
+```bash
+python3 nowcast-point-get.py idler.txt --output sonuc.csv                   # registrationId listesi (TXT), CSV çıktı
+python3 nowcast-point-get.py idler.csv --output sonuc.txt                   # registrationId sütunlu CSV, JSON Lines çıktı
+python3 nowcast-point-get.py alicilar.txt --by recipient --output sonuc.csv # recipientId ile sorgu
+```
+
+TXT girdi örneği (`idler.txt`):
+
+```text
+# bu satır atlanır
+f7587d9e-2481-4b4c-818d-c8d1946851b7
+57d1e2ba-bf2d-4ef3-b078-523060b2000c
+```
+
 Girdi CSV ise başlıkta `registrationId` (veya `recipientId`) sütunu aranır; TXT ise satır başına bir ID yazılır, boş satırlar ve `#` ile başlayanlar atlanır. `--output` zorunludur; uzantı `.csv` ise noktalı virgüllü CSV, `.txt` ise JSON Lines yazılır. Satır durumları `SUCCESS`, `NOT_FOUND` (HTTP 404) ve `FAILED`'dır (`httpStatus` ve `errorBody` dolar). Bir `recipientId` birden çok kayıt dönerse her kayıt ayrı satırdır.
 
 ### register
 
+```bash
+cp nowcast-point-alarm-filter.example.json nowcast-point-alarm-filter.json   # filtreleri düzenleyin
+python3 nowcast-point-register.py nowcast-point-registrations.example.csv
+python3 nowcast-point-register.py kayitlar.csv --filter-config baska-filtre.json --webhook-config baska-webhook.json
+```
+
+Girdi CSV örneği (sonuç sütunları işlem sonunda aynı dosyaya eklenir):
+
+```csv
+recipientId;lat;lng;radius
+musteri-001;39.9208;32.8541;1000
+musteri-002;41.0082;28.9784;5000
+```
+
 CSV sütunları yalnızca `recipientId;lat;lng;radius` değerleridir (`radius` metre, 0-50000). Filtre CSV'de tekrarlanmaz; ortak `nowcast-point-alarm-filter.json` dosyasından okunur ve her kayda uygulanır (`--filter-config` ile değiştirilir). Sonuç sütunları aynı dosyaya yazılır: `status;httpStatus;registrationId;errorBody`. HTTP 200 dışındaki yanıtlarda cevap gövdesi `errorBody` içine yazılır. `SUCCESS` satırlar yeniden çalıştırmada atlanır. Sonucu belirsiz kalan istek yalnızca `recipientId`, nokta ve yarıçap birebir eşleşirse mevcut kayıtla kurtarılır. Aynı hesap, `recipientId`, nokta ve yarıçap ikinci kez kaydedilemez (400).
 
 ### update
 
+```bash
+python3 nowcast-point-update.py guncelle.csv --dry-run   # gövdeleri gösterir, istek göndermez
+python3 nowcast-point-update.py guncelle.csv             # gerçekten günceller
+```
+
+Girdi CSV örneği (boş hücre gönderilmez):
+
+```csv
+registrationId;recipientId;lat;lng;radius;lightningType;peakCurrent;inCloudHeight;intersectsAffectedPolygon;intersectsCellPolygon;severityThreshold;speedThreshold;precipitationIntensities
+f7587d9e-2481-4b4c-818d-c8d1946851b7;;;;2500;;;;;;HIGH;;LIGHT|MODERATE
+57d1e2ba-bf2d-4ef3-b078-523060b2000c;;40.0;33.0;;PULSE_IN_CLOUD;;;;true;;;
+```
+
 CSV'de `registrationId` zorunludur; `recipientId;lat;lng;radius` ve filtre sütunları (`lightningType;peakCurrent;inCloudHeight;intersectsAffectedPolygon;intersectsCellPolygon;severityThreshold;speedThreshold;precipitationIntensities`, liste `|` ile ayrılır) isteğe bağlıdır. **Boş hücre gönderilmez**; `lat` ve `lng` birlikte verilmelidir. Önce `--dry-run` ile gövdeleri kontrol edin.
 
 - Backend PATCH'i bir alanı **temizleyemez** (null = dokunma).
@@ -207,4 +248,13 @@ CSV'de `registrationId` zorunludur; `recipientId;lat;lng;radius` ve filtre sütu
 
 ### unregister
 
+```bash
+python3 nowcast-point-unregister.py silinecekler.txt                                  # yedek alır, SİL onayı ister
+python3 nowcast-point-unregister.py silinecekler.csv --output sonuc.csv               # sonuçları dosyaya da yazar
+python3 nowcast-point-unregister.py silinecekler.txt --backup yedek/point-yedek.csv   # yedek yolu
+python3 nowcast-point-unregister.py silinecekler.txt --no-backup                      # yedeksiz (önerilmez)
+```
+
+Girdi `registrationId` içeren bir CSV veya satır başına bir ID içeren TXT olabilir.
+
 Başlamadan önce ortam adı ve URL, silinecek kayıt sayısı ve "geri alınamaz" uyarısı gösterilir; bir hesabın **son kaydı** silinirse webhook tanımı da silinir. Onay için `SİL` yazılmalıdır (`--yes` yoktur). `prod` ortamında ek olarak ortam adı (`prod`) yazdırılır. Silmeden önce her kayıt `get-by-id` ile yedeklenir (`--backup`, kapatmak için `--no-backup`); yedek yazılamazsa hiçbir kayıt silinmez.