natureco-sdk

NatureCo SDK

Official JavaScript SDK for NatureCo API - Build powerful AI chatbots and integrate them across multiple platforms.

📦 Installation

npm install natureco-sdk

Or using yarn:

yarn add natureco-sdk

For browser usage via CDN:

<script src="https://unpkg.com/natureco-sdk@latest/index.js"></script>

🚀 Quick Start

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

// Initialize the client with your API key
const client = new NatureCoClient('nco_your_api_key_here');

// Create a new bot
const bot = await client.bots.create({
  name: 'My First Bot',
  systemPrompt: 'You are a helpful assistant.',
  model: 'gpt-4'
});

console.log('Bot created:', bot);

🔑 Authentication

Getting Your API Key

• Go to NatureCo Developers Portal
• Navigate to API Keys section
• Click Generate New Key
• Copy your API key — new keys start with nco_; older nc_ keys keep working

Initialize Client

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

const client = new NatureCoClient('nco_your_api_key_here', {
  baseURL: 'https://api.natureco.me/api/v1', // Optional: custom API endpoint
  timeout: 30000 // Optional: request timeout in ms (default: 30000)
});

🪪 NatureCo Account (SSO)

NatureCoClient uses an API key for bot/automation access. A NatureCo account is different — it's a person's single identity, shared across the whole ecosystem (the CLI, Cupertino Terminal and the developer portal all sign in to the same account). Use NatureCoAuth for that.

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

const auth = new NatureCoAuth();
// In Node the session is stored in ~/.natureco/auth.json (0600) and shared
// with the NatureCo CLI/terminal; in the browser it's kept in memory.

// Password sign-in
await auth.loginWithPassword('[e-mail]', 'your-password');

// Or passwordless: send a code/login link to the email…
await auth.sendOtp('[e-mail]');
// …then verify. Depending on your email template the user receives either a
// 6-digit code or a magic login link:
await auth.verifyOtp('[e-mail]', '123456');   // 6-digit code
await auth.verifyLink('https://natureco.me/#access_token=…'); // pasted login link

const me = await auth.whoami();   // { id, email, … } or null
auth.isLoggedIn();                // boolean
auth.logout();

verifyLink() accepts the full URL from a magic-link email. It handles both the implicit flow (the link fragment already carries access_token/refresh_token) and the token_hash flow. Pass a custom { store } in the constructor to persist the session somewhere other than the default.

🤖 Bot Management

Create a Bot

const bot = await client.bots.create({
  name: 'Customer Support Bot',
  systemPrompt: 'You are a friendly customer support assistant. Help users with their questions.',
  model: 'gpt-4' // Options: 'gpt-4', 'gpt-3.5-turbo', 'claude-3'
});

console.log('Bot ID:', bot.botId);

List All Bots

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

bots.forEach(bot => {
  console.log(`${bot.name} (${bot.botId})`);
});

Get Bot Details

const bot = await client.bots.get('bot_123456');

console.log('Bot name:', bot.name);
console.log('System prompt:', bot.systemPrompt);
console.log('Model:', bot.model);

Update a Bot

const updatedBot = await client.bots.update('bot_123456', {
  name: 'Updated Bot Name',
  systemPrompt: 'New system prompt',
  model: 'gpt-4'
});

Delete a Bot

await client.bots.delete('bot_123456');
console.log('Bot deleted successfully');

📱 Channel Integration

Connect your bot to Discord, Telegram, Slack, Instagram, and more.

Connect Discord

const channel = await client.channels.connect({
  botId: 'bot_123456',
  platform: 'discord',
  token: 'your_discord_bot_token',
  config: {
    guildId: 'your_guild_id', // Optional
    commandPrefix: '!' // Optional
  }
});

Connect Telegram

const channel = await client.channels.connect({
  botId: 'bot_123456',
  platform: 'telegram',
  token: 'your_telegram_bot_token'
});

Connect Slack

const channel = await client.channels.connect({
  botId: 'bot_123456',
  platform: 'slack',
  token: 'xoxb-your-slack-bot-token',
  config: {
    signingSecret: 'your_signing_secret'
  }
});

Connect Instagram

const channel = await client.channels.connect({
  botId: 'bot_123456',
  platform: 'instagram',
  token: 'your_instagram_access_token',
  config: {
    pageId: 'your_page_id',
    verifyToken: 'your_verify_token'
  }
});

List Connected Channels

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

channels.forEach(channel => {
  console.log(`${channel.platform}: ${channel.isActive ? 'Active' : 'Inactive'}`);
});

Disconnect a Channel

await client.channels.disconnect('bot_123456', 'channel_789');
console.log('Channel disconnected');

Test Channel Connection

const result = await client.channels.test('bot_123456', 'channel_789');
console.log('Test result:', result.success ? 'Passed' : 'Failed');

💬 Messaging

Send a Message

const response = await client.messages.send({
  botId: 'bot_123456',
  message: 'Hello! How can I help you today?',
  channel: 'web', // 'web', 'discord', 'telegram', etc.
  userId: 'user_123'
});

console.log('Bot response:', response.reply);

Get Message History

const messages = await client.messages.history({
  botId: 'bot_123456',
  limit: 50,
  offset: 0
});

messages.forEach(msg => {
  console.log(`[${msg.timestamp}] ${msg.userId}: ${msg.message}`);
  console.log(`Bot: ${msg.reply}`);
});

Get Specific Message

const message = await client.messages.get('bot_123456', 'msg_789');
console.log('Message:', message);

🔔 Webhooks

Receive real-time notifications when events occur.

Create a Webhook

const webhook = await client.webhooks.create({
  botId: 'bot_123456',
  url: 'https://your-domain.com/webhook',
  events: ['message.received', 'message.sent', 'bot.error'],
  secret: 'your_webhook_secret' // Optional: for signature verification
});

console.log('Webhook ID:', webhook.id);

Available Events

• message.received - New message received from user
• message.sent - Bot sent a message
• bot.error - Bot encountered an error
• channel.connected - New channel connected
• channel.disconnected - Channel disconnected
• user.joined - New user started conversation
• analytics.daily - Daily analytics summary

List Webhooks

const webhooks = await client.webhooks.list('bot_123456');

webhooks.forEach(webhook => {
  console.log(`${webhook.url}: ${webhook.active ? 'Active' : 'Inactive'}`);
});

Update Webhook

const updated = await client.webhooks.update('bot_123456', 'webhook_789', {
  url: 'https://new-domain.com/webhook',
  events: ['message.received'],
  active: true
});

Delete Webhook

await client.webhooks.delete('bot_123456', 'webhook_789');

Test Webhook

const result = await client.webhooks.test('bot_123456', 'webhook_789');
console.log('Test result:', result);

View Webhook Logs

const logs = await client.webhooks.logs('bot_123456', 'webhook_789', 20);

logs.forEach(log => {
  console.log(`[${log.timestamp}] ${log.event}: ${log.status}`);
});

Webhook Payload Example

// Your webhook endpoint will receive:
{
  "event": "message.received",
  "timestamp": "2024-01-15T10:30:00Z",
  "botId": "bot_123456",
  "data": {
    "messageId": "msg_789",
    "userId": "user_123",
    "message": "Hello bot!",
    "channel": "discord",
    "metadata": {
      "username": "john_doe",
      "channelId": "channel_456"
    }
  }
}

Verify Webhook Signature

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(JSON.stringify(payload)).digest('hex');
  return signature === digest;
}

// In your webhook handler:
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-natureco-signature'];
  const isValid = verifyWebhookSignature(req.body, signature, 'your_webhook_secret');
  
  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process webhook...
  res.status(200).send('OK');
});

🎨 Web Widget

Embed a chat widget on your website.

Basic Embed

const embedCode = client.widget.getEmbedCode('bot_123456');
console.log(embedCode);
// Output: <script src="https://api.natureco.me/widget.js" data-bot-id="bot_123456" data-theme="light" data-position="bottom-right"></script>

Custom Theme and Position

const embedCode = client.widget.getEmbedCode({
  botId: 'bot_123456',
  theme: 'dark', // 'light' or 'dark'
  position: 'bottom-left' // 'bottom-right', 'bottom-left', 'top-right', 'top-left'
});

HTML Integration

<!DOCTYPE html>
<html>
<head>
  <title>My Website</title>
</head>
<body>
  <h1>Welcome to my website</h1>
  
  <!-- Add this before closing </body> tag -->
  <script 
    src="https://api.natureco.me/widget.js" 
    data-bot-id="bot_123456" 
    data-theme="dark" 
    data-position="bottom-right"
    data-welcome-message="Hi! How can I help you today?"
    data-primary-color="#22c55e">
  </script>
</body>
</html>

Update Widget Settings

await client.widget.updateSettings({
  botId: 'bot_123456',
  theme: 'dark',
  position: 'bottom-right',
  welcomeMessage: 'Hello! How can I assist you?',
  primaryColor: '#22c55e'
});

Get Widget Settings

const settings = await client.widget.getSettings('bot_123456');
console.log('Widget settings:', settings);

Widget Customization Options

<script 
  src="https://api.natureco.me/widget.js" 
  data-bot-id="bot_123456"
  data-theme="dark"
  data-position="bottom-right"
  data-welcome-message="Hi there! 👋"
  data-primary-color="#22c55e"
  data-button-size="60"
  data-window-width="400"
  data-window-height="600"
  data-z-index="9999">
</script>

📊 Analytics

Get Bot Analytics

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

console.log('Total messages:', analytics.totalMessages);
console.log('Active users:', analytics.activeUsers);
console.log('Average response time:', analytics.avgResponseTime);

Message Analytics

const messageStats = await client.analytics.messages('bot_123456', {
  startDate: '2024-01-01',
  endDate: '2024-01-31'
});

console.log('Messages sent:', messageStats.sent);
console.log('Messages received:', messageStats.received);

Channel Analytics

const channelStats = await client.analytics.channels('bot_123456');

channelStats.forEach(channel => {
  console.log(`${channel.platform}: ${channel.messageCount} messages`);
});

User Analytics

const users = await client.analytics.users('bot_123456', { limit: 100 });

users.forEach(user => {
  console.log(`${user.userId}: ${user.messageCount} messages, last seen ${user.lastSeen}`);
});

👤 User Management

Get Current User

const user = await client.user.me();

console.log('User ID:', user.id);
console.log('Display name:', user.displayName);
console.log('Email:', user.email);

Update User Profile

await client.user.update({
  displayName: 'John Doe',
  bio: 'AI enthusiast and developer',
  avatar: 'https://example.com/avatar.jpg'
});

🔐 API Key Management

List API Keys

const keys = await client.apiKeys.list();

keys.forEach(key => {
  console.log(`${key.name}: ${key.scopes.join(', ')}`);
});

Create New API Key

const newKey = await client.apiKeys.create({
  name: 'Production Key',
  scopes: ['bots:read', 'bots:write', 'messages:send']
});

console.log('New API key:', newKey.key);
// IMPORTANT: Save this key securely, it won't be shown again!

Revoke API Key

await client.apiKeys.revoke('key_123456');
console.log('API key revoked');

🛠️ Advanced Usage

Error Handling

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

try {
  const bot = await client.bots.create({
    name: 'My Bot',
    systemPrompt: 'You are helpful.'
  });
} catch (error) {
  if (error instanceof NatureCoError) {
    console.error('API Error:', error.message);
    console.error('Status code:', error.statusCode);
    console.error('Response:', error.response);
  } else {
    console.error('Unexpected error:', error);
  }
}

Custom Timeout

const client = new NatureCoClient('nco_your_api_key', {
  timeout: 60000 // 60 seconds
});

Custom Base URL (Self-hosted)

const client = new NatureCoClient('nco_your_api_key', {
  baseURL: 'https://your-custom-domain.com/api/v1'
});

Retry Logic

async function retryRequest(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)));
    }
  }
}

// Usage
const bot = await retryRequest(() => 
  client.bots.create({
    name: 'My Bot',
    systemPrompt: 'You are helpful.'
  })
);

🌐 Browser Usage

<!DOCTYPE html>
<html>
<head>
  <title>NatureCo SDK Browser Example</title>
</head>
<body>
  <h1>Chat with Bot</h1>
  <input type="text" id="message" placeholder="Type a message...">
  <button onclick="sendMessage()">Send</button>
  <div id="response"></div>

  <script src="https://unpkg.com/natureco-sdk@latest/index.js"></script>
  <script>
    const client = new NatureCoClient('nco_your_api_key');

    async function sendMessage() {
      const message = document.getElementById('message').value;
      
      try {
        const response = await client.messages.send({
          botId: 'bot_123456',
          message: message,
          channel: 'web',
          userId: 'user_' + Date.now()
        });
        
        document.getElementById('response').innerText = response.reply;
      } catch (error) {
        console.error('Error:', error);
      }
    }
  </script>
</body>
</html>

📚 Complete Example

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

async function main() {
  // Initialize client
  const client = new NatureCoClient('nco_your_api_key');

  try {
    // Create a bot
    const bot = await client.bots.create({
      name: 'Customer Support Bot',
      systemPrompt: 'You are a helpful customer support assistant.',
      model: 'gpt-4'
    });
    console.log('✅ Bot created:', bot.botId);

    // Connect to Discord
    await client.channels.connect({
      botId: bot.botId,
      platform: 'discord',
      token: process.env.DISCORD_TOKEN
    });
    console.log('✅ Discord connected');

    // Create webhook
    const webhook = await client.webhooks.create({
      botId: bot.botId,
      url: 'https://your-domain.com/webhook',
      events: ['message.received', 'message.sent'],
      secret: 'your_secret'
    });
    console.log('✅ Webhook created:', webhook.id);

    // Get embed code for website
    const embedCode = client.widget.getEmbedCode({
      botId: bot.botId,
      theme: 'dark',
      position: 'bottom-right'
    });
    console.log('✅ Widget embed code:', embedCode);

    // Send a test message
    const response = await client.messages.send({
      botId: bot.botId,
      message: 'Hello! This is a test.',
      channel: 'web',
      userId: 'test_user'
    });
    console.log('✅ Bot response:', response.reply);

    // Get analytics
    const analytics = await client.analytics.get({
      botId: bot.botId,
      period: 'week'
    });
    console.log('✅ Analytics:', analytics);

  } catch (error) {
    console.error('❌ Error:', error.message);
  }
}

main();

🔗 Useful Links

• Official Documentation
• API Reference
• Developers Portal
• GitHub Repository
• Support

📄 License

MIT License - see LICENSE file for details

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

💬 Support

• Email: [e-mail]
• Discord: Join our community
• Twitter: @naturecofficial

📝 Changelog

v1.2.1 (Latest)

• Added TypeScript type definitions (index.d.ts) covering the full SDK — NatureCoClient, all modules, and NatureCoAuth

v1.2.0

• NatureCoAuth.verifyLink() — sign in from a magic login-link email (implicit + token_hash flows), works in Node and the browser
• verifyOtp() now falls back to the magiclink verification type, so both code- and link-style templates work
• Documented the NatureCo Account (SSO) flow in the README

v1.1.0

• Added NatureCoAuth — single NatureCo account (SSO) shared across the CLI, terminal and portal (password + passwordless OTP, session refresh)

v1.0.5

• Updated README with comprehensive examples
• Added webhook signature verification
• Improved error handling documentation
• Added browser usage examples

v1.0.4

• Added widget customization options
• Improved API key validation
• Bug fixes and performance improvements

v1.0.3

• Added analytics module
• Added user management
• Added API key management

v1.0.2

• Added webhook support
• Improved error handling
• Added timeout configuration

v1.0.1

• Initial release
• Bot management
• Channel integration
• Messaging support

Made with ❤️ by NatureCo

More from NatureCo

• Cupertino Terminal — A macOS-grade terminal for Windows, macOS and Linux — Rust core, no Electron, with a built-in end-to-end encrypted P2P remote shell
• NatureCo CLI — A terminal-native AI assistant: chat, a coding agent, automation, and bots on Telegram, Discord and Slack
• Urðr — Tree-structured memory for AI coding agents — plain Markdown you can git diff, no vector database
• CodeDNA — How much of a commit was written by AI, and does its author actually understand it?
• Verðandi — Task-context compiler for AI coding agents — indexes with the TypeScript AST so the agent stops burning tokens hunting for the right file

_{Part of the NatureCo ecosystem — natureco.me · NatureCo ekosisteminin parçası}