TypeScript SDK
Node.js + tarayıcı (browser) için tür güvenli (type-safe) Moonborn istemcisi. OpenAPI'den otomatik üretilir; akış (streaming) AsyncIterable; eşgüçlülük (idempotency) + yeniden deneme (retry) yerleşik.
@moonborn/sdk — resmi TypeScript SDK'sıdır. Node.js 18+ ve modern tarayıcılarda çalışır. Kanonik OpenAPI belirtiminden otomatik üretilir; her API sürümüyle bir hafta içinde güncellenir.
Bu sayfayı bitirdiğinde
- TypeScript SDK'sını kurabilecek ve başlatabileceksin.
- Persona oluşturma + sohbet + akışı uçtan uca çağırabileceksin.
- AsyncIterable akış desenini kullanabileceksin.
- Yeniden deneme + eşgüçlülük (idempotency) yerleşik davranışını anlayacaksın.
- Hata işleme zarfını (
MoonbornAPIError) doğru yakalayabileceksin.
Ön koşul: Node.js 18+ veya modern tarayıcı; API anahtarı (MOONBORN_API_KEY).
Kurulum
pnpm add @moonborn/sdk
# veya
npm install @moonborn/sdk
# veya
yarn add @moonborn/sdkBaşlatma (initialize)
import Moonborn from '@moonborn/sdk';
const client = new Moonborn({
apiKey: process.env.MOONBORN_API_KEY,
// İsteğe bağlı
baseURL: 'https://api.moonborn.co', // kendi sunucuna kurulum (self-hosted) için geçersiz kıl
timeout: 60_000, // istek zaman aşımı (ms)
maxRetries: 3, // yeniden denenebilir hatalar için
});Ortam değişkeni yedeği: MOONBORN_API_KEY, MOONBORN_BASE_URL otomatik okunur.
Persona oluşturma
const persona = await client.personas.create({
intent: 'Bahçeyle takıntılı, İstanbul\'da yaşayan emekli bir cerrah.',
options: {
pipeline: {
audit: { enabled: true },
voiceFingerprint: { enabled: true },
},
},
});
console.log(persona.id, persona.surface.name.display);Akış (streaming) ile üretim
const stream = await client.personas.createStream({
intent: 'Lagos\'ta sokak-akıllı bir market satıcısı.',
});
for await (const event of stream) {
switch (event.type) {
case 'step.started':
console.log('Başladı:', event.step);
break;
case 'step.completed':
console.log('Bitti:', event.step, event.durationMs);
break;
case 'pipeline.completed':
console.log('Persona:', event.personaId);
break;
}
}6 görünür adım — intent_parse → soul_draft → self_enrich → mask_build → surface_ground → audit. Detay: Akış desenleri.
Sohbet — akışlı
const session = await client.chat.sessions.create({ personaId: persona.id });
const stream = client.chat.messages.stream({
sessionId: session.id,
content: 'Sessiz bir gerçek söyle.',
});
let driftScore = 0;
for await (const chunk of stream) {
if (chunk.type === 'token') {
process.stdout.write(chunk.delta);
} else if (chunk.type === 'completed') {
driftScore = chunk.driftScore;
}
}
console.log('\nDrift:', driftScore);stream bir AsyncIterable — for await ... of doğrudan çalışır.
Sohbet — akışsız
const reply = await client.chat.messages.create({
sessionId: session.id,
content: 'En büyük korkun ne?',
});
console.log(reply.content);
console.log('Drift:', reply.driftScore, 'Alert:', reply.driftAlert);İptal — akışı kes
const controller = new AbortController();
const stream = client.chat.messages.stream(
{ sessionId: session.id, content: '...' },
{ signal: controller.signal },
);
setTimeout(() => controller.abort(), 2000); // 2 sn sonra iptal
for await (const chunk of stream) {
// ...
}İptal sinyali Moonborn tarafında algılanır; LLM çağrısı kesilir, kalan token'lar faturalandırılmaz. Detay: Akış desenleri.
Hata işleme
import Moonborn, { MoonbornAPIError } from '@moonborn/sdk';
try {
await client.personas.create({ intent: '...' });
} catch (err) {
if (err instanceof MoonbornAPIError) {
switch (err.code) {
case 'rate_limited':
await sleep(err.details.retryAfter * 1000);
// yeniden dene
break;
case 'validation_failed':
console.error('Body invalid:', err.details.validationErrors);
break;
case 'forbidden':
console.error('Yetki kapsamı (scope) / rol eksik');
break;
}
} else {
throw err; // ağ hatası vb.
}
}14 kodluk katalog: Hatalar.
Eşgüçlülük (idempotency)
Her yazma isteği bir Idempotency-Key başlığı kabul eder. SDK varsayılan olarak UUID otomatik üretir; belirli (deterministik) bir iş anahtarı (business key) kullanmak için geçersiz kıl:
const persona = await client.personas.create(
{ intent: '...' },
{ idempotencyKey: 'persona-build-2026-05-17-mert' },
);24 saat içinde yeniden gönderilen istekler orijinal yanıtı döndürür. Detay: Hatalar / Idempotency.
Geri basınç (backpressure) geri çağırması
const client = new Moonborn({
apiKey: process.env.MOONBORN_API_KEY,
onRateLimitNearCap: ({ remaining, resetIn }) => {
if (remaining < 50) {
console.warn(`Hız limiti yaklaşıyor: ${remaining} kaldı, ${resetIn}s reset`);
// Kuyruğu kıs, operasyona uyarı vb.
}
},
});Detay: Hız limitleri.
OpenAPI'den otomatik üretim
SDK kaynağı packages/sdk-ts/ altındadır; OpenAPI 3.1 belirtiminden üretilir. Her API sürümünde otomatik yenilenir. Özel değişiklik istiyorsan kendi istemcini üret (orval, oazapfts, openapi-typescript) — detay: SDK'lar dizini.
Sık karşılaşılan hatalar
"Cannot read property 'apiKey' of undefined"
Moonborn({ ... }) çağrısında apiKey eksik. Ortam değişkeninden otomatik yükleme için MOONBORN_API_KEY ayarla veya yapıcıya (constructor) geçir.
Akış yarıda kesiliyor
Ağ zaman aşımı. SDK 30 sn zaman aşımı varsayılanını kullanır; akışlar için timeout: 0 (devre dışı) veya yüksek bir değer geçir:
const client = new Moonborn({
apiKey: '...',
timeout: 0, // akış (streaming) için
});"MoonbornAPIError: drift_blocked"
Drift detection action: block modu aktiftir. Çalışma alanı yapılandırmasını kontrol et — üretimde (production) auto_recover veya warn kullan. Detay: Drift detection.
Plan gereksinimi
Her plan — özellik kapıları sunucu tarafındadır.