JavaScript SDK

CID222'nin API'si kitaplıksız çağrılabilecek kadar küçüktür: sohbet isteği göndermek için bir rota, metin taramak için bir rota, erişebildiğiniz modelleri listelemek için bir rota. Bir istemci kitaplığının sizi kurtaracağı asıl kısım, insanları şaşırtan kısımdır — yanıt, OpenAI veya Anthropic uyumlu bir yük değil, kendine özgü biçimi olan bir sunucu tarafından gönderilen olay akışıdır.

Bir istemci kitaplığının gizlemesi gereken şeyler

• Akışsız bir mod yoktur. POST /chat/completions her zaman text/event-stream ile yanıt verir. İstek gövdesindeki stream alanı kabul edilir ve sonra yok sayılır; bu nedenle response.json() her çağrıda başarısız olur.
• Cevap parçacıklar hâlinde değil, tek olay olarak gelir. Ağ geçidi sağlayıcının token'larını tüketir, tam cevabı tamponlar, üzerinde çıktı filtresini çalıştırır ve {"id":"filtered-response","content":…,"finish_reason":"stop"} olayını bir kez yayar. choices[].delta yoktur, content_block_delta yoktur ve kademeli olarak gösterilecek bir şey yoktur.
• Politika engellemesi bir hata durumu değildir. Reddedilen bir istem, 200 yanıtı üzerinde bir olaydır.
• İki sohbet yüzeyi reddetme konusunda uyuşmaz. /chat/completions bir error alanı kullanır; /sessions/:id/messages ise error alanı olmadan {"type":"content_rejected","reason":…} kullanır.
• Her rota aynı kimlik bilgisini kabul etmez. Bir cid_key_ taşıyıcısı /chat/completions, /models ve /api/v1/guardrails/detect üzerinde çalışır. Oturumlar, görüntü analizi ve belge analizi kullanıcı JWT'si gerektirir.

Bugün REST API'yi kullanın

Bu istemci, Node 18 ve sonrasında yukarıdaki sözleşmeye karşı çalışır; tarayıcıda ise yalnızca kendi sunucu rotanızın arkasında — bir ağ geçidi anahtarı asla ön yüz koduna ulaşmamalıdır.

const GATEWAY = 'https://<gateway-host>';
 
export async function chat({ model, provider, messages, maxTokens }) {
  const res = await fetch(`${GATEWAY}/chat/completions`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.CID222_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ model, provider, messages, max_tokens: maxTokens }),
  });
 
  if (!res.ok) {
    // 400/401/402/403/423 arrive here. The body may or may not carry a `code`.
    const body = await res.json().catch(() => ({}));
    const error = new Error(body.message ?? `Gateway returned ${res.status}`);
    error.status = res.status;
    error.code = body.code;
    throw error;
  }
 
  const reader = res.body.getReader();
  const decoder = new TextDecoder();
  let buffer = '';
  let answer = '';
  let usage = null;
 
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    buffer += decoder.decode(value, { stream: true });
 
    // Frames are separated by a blank line. Keep the trailing partial frame.
    const frames = buffer.split('\n\n');
    buffer = frames.pop() ?? '';
 
    for (const frame of frames) {
      const line = frame.split('\n').find((l) => l.startsWith('data: '));
      if (!line) continue;
      const data = line.slice(6).trim();
      if (data === '[DONE]') return { answer, usage };
 
      const event = JSON.parse(data);
 
      // Prompt blocked before the provider was called, or a server-side failure.
      if (event.error) throw new Error(event.error);
      // Answer discarded by the output filter.
      if (event.type === 'output_content_rejected') throw new Error(event.reason);
      if (event.type === 'token_usage') { usage = event.usage; continue; }
      if (event.type) continue; // routing, compression and warning telemetry
 
      // The whole filtered answer, as one event.
      if (typeof event.content === 'string') answer = event.content;
    }
  }
 
  return { answer, usage };
}

Metin taramak için akış işleme gerekmez — tespit uç noktası düz JSON döndürür:

export async function detect(text, checkType = 'prompt') {
  const res = await fetch(`${GATEWAY}/api/v1/guardrails/detect`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.CID222_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ text, check_type: checkType }),
  });
  if (!res.ok) throw new Error(`Detection returned ${res.status}`);
  // { action, detectedEntities, detectionCount, maskedText, processingTimeMs, … }
  return res.json();
}

Kitaplığın kapsaması planlanan şeyler

Bunlar niyettir, yayımlanmış davranış değildir. Buradaki hiçbir şey bugün çağrılabilir değildir.

• Tipli istekler ve yanıtlar, ağ geçidinin kendi DTO'larından üretilir; böylece adı değişen bir alan, sessizce çıkarılan bir gövde alanı yerine bir derleme hatası olur.
• Akış işleme, çerçeve birleştirme ve sonlandırıcı olaylar dâhil, tek bir await arkasında.
• Ayrı hata türleri; bir taşıma hatası, bir politika reddi ve bir lisans veya rol reddi için — böylece çağıran, durum kodlarını ve isteğe bağlı code alanlarını incelemeden dallanabilir.
• Bağlantı havuzlama, bir kez yapılandırılan keep-alive ile.
• Oturum desteği, yalnızca JWT kısıtı ve belirteç yenileme dâhil.

Sınırlar ve bilinen eksikler

• Böyle bir paket yoktur. Herhangi bir genel kayıt defterinde bulacağınız @cid222/… adı bu proje tarafından yayımlanmamıştır. Kurmayın.
• Yayın tarihi yoktur. Yukarıdaki planlanan listeyi bir taahhüt değil, bir yön olarak görün.
• Resmî tip tanımları yoktur. Kitaplık yayımlanana kadar DTO'ları Sohbet tamamlamaları sayfasından elle yansıtın ve ağ geçidini yükselttiğinizde yeniden kontrol edin.
• Bilinmeyen istek alanları sessizce düşürülür. Tipli bir istemci olmadan, yanlış yazılmış bir alan adı ayarınızı yok sayan başarılı bir çağrı üretir.
• Bir tarayıcı ağ geçidini anahtarla doğrudan çağıramaz. Bir cid_key_ değerini elinde tutan her şey kiracının sağlayıcı bütçesini harcayabilir; bu nedenle kimlik bilgisi sunucunuzda kalır.

İlgili sayfalar

• Entegrasyon örnekleri — aynı istemci adım adım bir yordam olarak, ayrıca Python, cURL ve React.
• Hata yönetimi — durum kodları, üç hata gövdesi biçimi ve reddetme olayları.
• Python SDK — Python tarafındaki aynı durum.