Python SDK
pushizo (PyPI) — Python 3.9+, httpx; OpenAPI'den üretilen modeller ve kaynak metotları, yeniden deneme, idempotency, sayfalama, webhook imza doğrulaması.
Kaynak: sdk/python. Modeller ve kaynak metotları api/openapi.yaml'dan üretilir (npm run sdk:generate); kimlik doğrulama, yeniden deneme, idempotency, sayfalama ve webhook imza doğrulaması el yazımı katmandadır.
Kurulum
pip install pushizoKullanım
import os
from pushizo import Pushizo
hs = Pushizo(api_key=os.environ["HS_API_KEY"], app_id="app_…") # yerelde base_url="http://localhost:4000"
# Bildirim gönder (idempotency_key verilmezse otomatik UUID; yeniden denemelerde aynı anahtar kullanılır)
res = hs.notifications.create(
{
"target": {"include_aliases": {"external_id": ["user-42"]}},
"contents": {"en": "Your order shipped", "tr": "Siparişiniz kargoya verildi"},
},
idempotency_key="order-1001",
)
print(res["id"], res["status"])
# Kullanıcı oluştur/güncelle ve abonelik ekle
hs.users.upsert({"external_id": "user-42", "tags": {"plan": "pro"}})
hs.users.add_subscription("external_id", "user-42", {"channel": "email", "token": "ayse@example.com"})
# Cursor sayfalama: tüm sayfaları dolaşır
for segment in hs.segments.list_all(limit=100):
print(segment["name"])
# Başka bir app için tek çağrı
hs.apps.get(app_id="app_diger")
# SDK identity verification: identity_hash = HMAC-SHA256(sdk_secret, external_id)
identity_hash = Pushizo.identity_hash(os.environ["HS_SDK_SECRET"], "user-42")Modeller çalışma zamanında sade dict'tir; tipler pushizo._generated.models içindeki TypedDict'lerle (CreateNotificationDto, Message …) editörde görünür. Kaynak adları OpenAPI etiketleriyle aynıdır (notifications, users, aliases, subscriptions, events, channels, segments, templates, campaigns, journeys, in_app_messages, inbox, categories, preferences, suppressions, webhooks, analytics, exports, imports, api_keys, apps, organization); metot adları snake_case'tir (campaigns.variant_stats, campaigns.select_winner, in_app_messages.select_winner, organization.usage; in_app_messages.winner eski addır ve kullanımdan kaldırılmıştır). SDK'da metodu olmayan uçlar ve JSON dışı yanıtlar için:
hs.request("GET", "/v1/apps/app_…/analytics/messages", query={"format": "csv"})Ayarlar
| Parametre | Varsayılan | Açıklama |
|---|---|---|
api_key | — | hs_live_… API anahtarı (Bearer) |
app_id | None | Çağrıda app_id= verilmezse kullanılan app |
base_url | https://api.pushizo.com | API adresi |
timeout | 30 | Deneme başına zaman aşımı (sn) |
max_retries | 3 | En fazla yeniden deneme (politika) |
auto_idempotency_key | True | Idempotency-Key destekleyen çağrılarda otomatik UUID |
http_client | — | Özel httpx.Client (proxy, TLS) |
Her çağrı request_options={"timeout": 5, "max_retries": 0, "headers": {...}} ile ayrıca ayarlanabilir.
Hatalar
Yeniden denemeler aşağıdaki politikaya göre yapılır. Kalıcı hatalar PushizoError'dan türer ve status, code (HS_…), request_id, details taşır:
from pushizo import ErrorCode, NotFoundError, RateLimitError, PushizoError
try:
hs.notifications.get("msg_yok")
except NotFoundError as e:
print(e.code == ErrorCode.NOT_FOUND, e.request_id)
except RateLimitError:
...
except PushizoError as e: # InvalidRequestError, AuthenticationError, PermissionDeniedError, ConflictError, ServerError, NetworkError
print(e.status, e.code, e.message)Yeniden deneme politikası
Yeniden denemeler üstel geri çekilmeyle (0,3 / 1 / 3 sn; Retry-After başlığı varsa ona uyulur) en fazla max_retries kez yapılır. Sunucuda tekrarlanması güvenli olmayan isteklerin çift işlenmemesi için kural HTTP metoduna göre değişir:
| Durum | GET, HEAD, OPTIONS, PUT, DELETE | POST, PATCH |
|---|---|---|
429 | Yeniden denenir | Yeniden denenir (istek işlenmeden reddedilmiştir) |
5xx, zaman aşımı, gönderim sonrası bağlantı kopması | Yeniden denenir | Yalnızca Idempotency-Key varsa |
İstek hiç gönderilemedi (httpx.ConnectError (bağlantı reddi, DNS hatası), ConnectTimeout, PoolTimeout) | Yeniden denenir | Yeniden denenir |
Diğer 4xx | Denenmez | Denenmez |
5xx ya da gönderim sonrası ağ hatasında sunucu isteği işlemiş olabilir; anahtarsız bir POST/PATCH tekrarı çift bildirim veya kayıt üretebilir. notifications.create ve users.upsert anahtar verilmezse otomatik UUID üretir (otomatik anahtar kapatılmadıysa), bu yüzden bu iki çağrı güvenle yeniden denenir. Başka bir POST/PATCH çağrısının da yeniden denenmesini istiyorsanız anahtarı kendiniz verin: hs.events.send(body, request_options={"idempotency_key": f"evt-{id}"}). Yeniden denemelerde aynı anahtar gönderilir; API aynı anahtarla 24 saat içinde gelen tekrarı ilk yanıtla karşılar.
Webhook imza doğrulaması
import os
from flask import Flask, request
from pushizo import WebhookSignatureError, construct_webhook_events
app = Flask(__name__)
@app.post("/hooks/pushizo")
def pushizo_hook():
try:
events = construct_webhook_events(
request.get_data(), # ham gövde
request.headers.get("Pushizo-Signature"),
os.environ["HS_WEBHOOK_SECRET"], # rotasyonda [eski, yeni] verilebilir
)
except WebhookSignatureError as e:
return e.reason, 400
for event in events: # tekil veya batch gövde
... # Pushizo-Event-Id ile tekrarları ayıklayın
return "", 204Zaman damgası 5 dakikadan eskiyse (tolerance_seconds) istek replay sayılır ve reddedilir. Olay türleri ve gövde: Webhook'lar.
Geliştirme
pip install -e ".[dev]" && pytest # sdk/python içinde
node sdk/scripts/generate-server-sdks.mjs --lang python # depo kökünde; modeller/kaynaklar yeniden üretilirPHP SDK
pushizo/pushizo-php — PHP ≥ 8.1, yalnızca ext-curl ve ext-json; bildirim, kullanıcı, olay, webhook imza doğrulama, journey ve tüm public API. Laravel örneği.
Go SDK
github.com/exec0de/pushizo/sdk/go — Go 1.23+, yalnızca standart kütüphane; üretilen modeller ve servisler, yeniden deneme, idempotency, range-over-func sayfalama, webhook imza doğrulaması.