SDK'lar — tür güvenli (type-safe) istemciler
6 dilde resmi SDK — TypeScript, Python, Go, Ruby, Rust, Elixir + komut satırı için CLI. Her biri kanonik OpenAPI belirtiminden üretilir; REST yüzeyiyle 1:1.
Moonborn 6 dilde resmi SDK + CLI (komut satırı arayüzü) gönderir. Hepsi kanonik OpenAPI belirtiminden (/openapi.json) üretilir; REST yüzeyiyle 1:1 eşleşir — sadece SDK veya sadece REST'te bulunan özellik yoktur.
Bu sayfa karar yardımıdır: hangi SDK senin için, sürüm uyumu nasıl, mevcut HTTP istemcinle nasıl kullanırsın.
Bu sayfayı bitirdiğinde
- 6 SDK + CLI'nin durum + paket adı + dil sürümünü bileceksin.
- SDK ↔ API sürüm sabitleme (pin) kuralını ayırt edebileceksin.
- Kendi HTTP istemcinle REST'i doğrudan çağırma örneğini göreceksin.
- OpenAPI belirtiminden kendi istemcini üretme akışını öğreneceksin.
Ön koşul: API anahtarı + tercih ettiğin dil çalışma zamanı.
Mevcut SDK'lar
| Dil | Paket | Durum | Detay |
|---|---|---|---|
| TypeScript | @moonborn/sdk | ✓ v1 kararlı (stable) | TypeScript SDK |
| Python | moonborn (PyPI) | ✓ v1 kararlı | Python SDK |
| Go | github.com/moon-born/sdk-go | ✓ v1 | Go SDK |
| Ruby | moonborn (RubyGems) | ✓ v1 | Ruby SDK |
| Rust | moonborn (crates.io) | ✓ v1 | Rust SDK |
| Elixir | moonborn (Hex) | ✓ v1 | Elixir SDK |
| CLI | @moonborn/cli (ikili: moonborn) | ✓ v1 | CLI |
TypeScript — hızlı bakış
pnpm add @moonborn/sdkimport Moonborn from '@moonborn/sdk';
const client = new Moonborn({ apiKey: process.env.MOONBORN_API_KEY });
const persona = await client.personas.create({
intent: 'A bookshop owner who reads more than she sells.',
});
const session = await client.chat.sessions.create({ personaId: persona.id });
for await (const chunk of client.chat.messages.stream({
sessionId: session.id,
content: 'Tell me a quiet truth.',
})) {
process.stdout.write(chunk.delta);
}Python — hızlı bakış
pip install moonbornimport os
from moonborn import Moonborn
client = Moonborn(api_key=os.environ["MOONBORN_API_KEY"])
persona = client.personas.create(
intent="A bookshop owner who reads more than she sells."
)
session = client.chat.sessions.create(persona_id=persona.id)
for chunk in client.chat.messages.stream(
session_id=session.id,
content="Tell me a quiet truth."
):
print(chunk.delta, end="", flush=True)Eşzamansız varyant: moonborn.aio.AsyncMoonborn.
SDK ↔ API sürüm uyumluluğu
Her SDK sürümü bir API alt sürümüne (minor version) sabitlidir:
| SDK sürümü | API sürümü |
|---|---|
@moonborn/sdk 1.4.x | 1.4.* ✓ |
@moonborn/sdk 1.4.x | 1.5.* ✓ (ileri uyumlu, eklemeli — additive) |
@moonborn/sdk 1.4.x | 2.0.* ✗ (büyük sürüm uyumsuzluğu) |
@moonborn/sdk 2.0.x | 1.x.* ✗ |
SDK yol sürümü uyumsuzluğunda (path-version mismatch) başlatmayı reddeder — savunmacı koruyucu (defensive guard). Detay: API sürümleme politikası.
Kendi HTTP istemcini getir
SDK eklemek istemiyorsan, REST yüzeyi SDK'ların sardığı yüzeyle aynıdır:
curl -X POST https://api.moonborn.co/v1/personas \
-H "Authorization: Bearer $MOONBORN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"intent": "..."}'Tüm uç noktalar HTTPS + taşıyıcı belirteç (bearer auth) + JSON girdi / çıktı.
OpenAPI belirtiminden özel istemci üret
/openapi.json her zaman güncel tutulur. Kendi istemcini üretmek için:
curl https://api.moonborn.co/openapi.json > openapi.json
# Örnek: openapi-generator (Java, Kotlin, Swift, C#, PHP, ...)
openapi-generator-cli generate \
-i openapi.json \
-g <language> \
-o ./moonborn-client
# Veya: orval (TypeScript, React Query, Zod)
npx orval --input openapi.json --output ./src/moonborn
# Veya: oazapfts (TypeScript, çalışma zamanı bağımlılığı yok)
npx oazapfts openapi.json src/moonborn.tsResmi SDK kapsamı dışındaki diller için yaygın seçim — Java, Kotlin, Swift, C#, PHP, .NET için openapi-generator standart desendir.
Hangi SDK?
| Senaryo | Tavsiye |
|---|---|
| Next.js / Node.js / tarayıcı uygulaması | TypeScript |
| FastAPI / Django / veri hattı | Python (eşzamansız için AsyncMoonborn) |
| Mikroservis (düşük gecikme süresi) | Go veya Rust |
| Rails / Sinatra | Ruby |
| Phoenix / GenServer / hata toleranslı | Elixir |
| Kabuk (shell) betikleri / CI / cron | CLI + jq |
| Java / Kotlin / Swift / C# | OpenAPI generator (resmi SDK yok) |
Plan gereksinimi
Tüm SDK'lar her planda çalışır — özellik kapıları (feature gates) sunucu tarafında uygulanır.