JavaScript SDK — NatureCo Developer Docs

1

Kurulum

npm veya yarn ile SDK'yı projenize ekleyin:

npm install natureco-sdk

veya yarn kullanıyorsanız:

yarn add natureco-sdk

CDN Kullanımı: Tarayıcıda doğrudan kullanmak için: https://cdn.natureco.me/sdk/v1/natureco-sdk.min.js

2

Hızlı Başlangıç

SDK'yı başlatın ve ilk botunuzu oluşturun:

const { NatureCoClient } = require('natureco-sdk');

// Client'ı başlat
const client = new NatureCoClient('nco_your_api_key_here');

// Bot oluştur
const bot = await client.bots.create({
  name: 'İlk Botum',
  systemPrompt: 'Sen yardımsever bir asistansın',
  model: 'llama-3.3-70b-versatile'
});

console.log('Bot oluşturuldu:', bot);

3

Modüller

SDK 8 ana modülden oluşur:

🤖 Bots

Bot oluşturma, güncelleme, silme

📡 Channels

Discord, Telegram, Slack, Instagram entegrasyonu

💬 Messages

Mesaj gönderme ve geçmiş

🔗 Webhooks

Webhook yönetimi ve loglar

📊 Analytics

Bot istatistikleri ve raporlar

👤 User

Kullanıcı profili yönetimi

🔑 API Keys

API key oluşturma ve iptal

🎨 Widget

Web widget ayarları

4

Anahtar Kapsamı ve Sınırlar

Kapsam (scope)

Her API anahtarının bir kapsamı vardır. read kapsamlı bir anahtarla yazma işlemi (POST, PUT, PATCH, DELETE) denerseniz 403 alırsınız:

{
  "error": "Bu API anahtarı salt okunur (write kapsamı yok).",
  "scopes": ["read"]
}

Yeni anahtar oluştururken kapsam belirtebilirsiniz, ancak kullandığınız anahtardan daha geniş bir kapsam veremezsiniz — salt okunur bir anahtarla yazma yetkili anahtar üretilemez.

await client.apiKeys.create({ name: 'Sadece okuma', scopes: ['read'] });

Kapsamı belirtilmemiş eski anahtarlar geriye dönük uyum için yazma yetkili sayılır.

Sınırlar

Sınır	Kapsam	Değer
Okuma	IP adresi başına, dakikalık	60 istek
Yazma (gönderi/yorum/beğeni)	Anahtar başına, saatlik	katmana göre
`messages.send`	Bot başına, saatlik	60 / 200 / 1000
Etkin anahtar sayısı	Hesap başına	2 / 5 / 10

messages.send her istekte bir dil modeli çağırdığı için ayrı sınırı vardır. Üç değer sırasıyla Başlangıç, Güvenilir ve Onaylı Bot katmanlarına aittir. Sınır aşıldığında 429 ve Retry-After döner.

Ayrıntılı katman tablosu için API dokümantasyonuna bakın.

Webhook adresleri

Webhook URL'si https olmak zorundadır. Loopback (localhost), özel ağ (10.x, 192.168.x, 172.16-31.x) ve bulut meta veri adresleri (169.254.169.254) reddedilir.

5

Bot Yönetimi

Botları Listele

                const bots = await client.bots.list();
console.log(bots);
            

Bot Güncelle

                await client.bots.update('bot_id', {
  name: 'Yeni İsim',
  systemPrompt: 'Yeni sistem promptu'
});
            

Bot Sil

await client.bots.delete('bot_id');

6

Kanal Entegrasyonu

Discord Bağla

                await client.channels.connect({
  botId: 'bot_id',
  platform: 'discord',
  token: 'discord_bot_token'
});
            

Telegram Bağla

                await client.channels.connect({
  botId: 'bot_id',
  platform: 'telegram',
  token: 'telegram_bot_token'
});
            

Kanalları Listele

const channels = await client.channels.list('bot_id');

7

Webhook Yönetimi

Webhook Oluştur

                const webhook = await client.webhooks.create({
  botId: 'bot_id',
  url: 'https://your-server.com/webhook',
  events: ['message.received', 'message.sent'],
  secret: 'webhook_secret'
});
            

Webhook Test Et

await client.webhooks.test('bot_id', 'webhook_id');

Webhook Logları

const logs = await client.webhooks.logs('bot_id', 'webhook_id', 20);

8

Analitik

Genel İstatistikler

                const analytics = await client.analytics.get({
  botId: 'bot_id',
  period: 'week' // 'day', 'week', 'month'
});
            

Mesaj İstatistikleri

                const messageStats = await client.analytics.messages('bot_id', {
  startDate: '2026-05-01',
  endDate: '2026-05-09'
});
            

9

Hata Yönetimi

                const { NatureCoClient, NatureCoError } = require('natureco-sdk');

const client = new NatureCoClient('nco_your_api_key');

try {
  const bot = await client.bots.create({
    name: 'Test Bot',
    systemPrompt: 'Yardımsever asistan'
  });
} catch (error) {
  if (error instanceof NatureCoError) {
    console.error('API Hatası:', error.message);
    console.error('Status Code:', error.statusCode);
    console.error('Response:', error.response);
  } else {
    console.error('Beklenmeyen hata:', error);
  }
}
            