> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suada.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Node.js SDK

> Learn how to integrate Suada with your Node.js applications

## Overview

The Suada Node.js SDK provides a simple and intuitive way to interact with the Suada API. It includes built-in TypeScript support and handles all the complexity of making API requests, managing authentication, and parsing responses.

## Prerequisites

* Node.js version 18.0.0 or higher
* A Suada API key
* npm or yarn package manager

## Installation

Install the Suada Node.js SDK using npm:

```bash theme={null}
npm install @suada/sdk
```

Or using yarn:

```bash theme={null}
yarn add @suada/sdk
```

## Quick Start

Here's a basic example to get you started:

```typescript theme={null}
import { Suada } from '@suada/sdk';

// Initialize the client
const suada = new Suada({
  apiKey: 'your-api-key'
});

// Send a chat message
async function chat() {
  try {
    const response = await suada.chat({
      message: 'What insights can you provide about our recent performance?'
    });
    console.log(response.answer);
  } catch (error) {
    console.error('Error:', error);
  }
}

chat();
```

## Authentication

### Setting up your API Key

We recommend storing your API key in environment variables:

```bash theme={null}
# .env
SUADA_API_KEY=your-api-key
```

Then load it in your application:

```typescript theme={null}
import dotenv from 'dotenv';
import { Suada } from '@suada/sdk';

dotenv.config();

const suada = new Suada({
  apiKey: process.env.SUADA_API_KEY
});
```

## Core Concepts

### Chat Messages

The chat endpoint is the primary way to interact with Suada. Each chat request can include:

* A message (required)
* Chat history (optional)
* Configuration options (optional)

```typescript theme={null}
const response = await suada.chat({
  message: "How's our business performing?",
  chatHistory: previousMessages, // Optional
  privacyMode: true            // Optional
});
```

### Response Format

Chat responses include several key components:

```typescript theme={null}
interface SuadaResponse {
  // The main response text
  answer: string;
  
  // Internal reasoning process (optional)
  thoughts?: string;
  
  // Actions taken during processing (optional)
  actions?: Array<{
    tool: string;
    toolInput: string;
    log: string;
  }>;
  
  // Suggested follow-up question (optional)
  followUpQuestion?: string;
  
  // Reasoning behind the response (optional)
  reasoning?: string;
  
  // Reference sources (optional)
  sources?: string[];
  
  // Conversation tracking ID (optional)
  conversationId?: string;
  
  // Response timestamp
  timestamp: number;
}
```

## Advanced Features

### LangChain Integration

The SDK provides seamless integration with LangChain, allowing you to use Suada's capabilities within your LangChain applications:

```typescript theme={null}
import { Suada } from '@suada/sdk';
import { AgentExecutor, createOpenAIFunctionsAgent } from 'langchain/agents';
import { ChatOpenAI } from 'langchain/chat_models/openai';
import { PromptTemplate } from 'langchain/prompts';

// Initialize Suada
const suada = new Suada({
  apiKey: process.env.SUADA_API_KEY
});

// Create a Suada tool for LangChain
const suadaTool = suada.createTool({
  name: 'business_analyst',
  description: 'Use this tool to get business insights and analysis',
  externalUserIdentifier: 'user-123' // Required if using passthrough mode
});

// Create an OpenAI agent with the Suada tool
const model = new ChatOpenAI({ temperature: 0 });
const tools = [suadaTool];

const prompt = PromptTemplate.fromTemplate(`
  You are a helpful assistant that uses Suada's business analyst capabilities.
  
  Current conversation:
  {chat_history}
  
  Human: {input}
  Assistant: Let me help you with that.
`);

const agent = await createOpenAIFunctionsAgent({
  llm: model,
  tools,
  prompt
});

const executor = AgentExecutor.fromAgentAndTools({
  agent,
  tools,
  verbose: true
});

// Use the agent
const result = await executor.invoke({
  input: "What's our revenue trend for the last quarter?",
  chat_history: []
});
```

#### LangChain Best Practices

1. **Tool Configuration**
   * Provide clear, specific descriptions for your tools
   * Use appropriate temperature settings for your use case
   * Consider implementing tool-specific error handling

2. **Agent Setup**
   * Use structured prompts for consistent behavior
   * Implement proper chat history management
   * Consider using memory for maintaining context

3. **Error Handling**
   * Implement proper error handling for both Suada and LangChain
   * Consider retry logic for transient failures
   * Log agent actions for debugging

4. **Performance**
   * Reuse agent instances when possible
   * Implement appropriate timeouts
   * Consider caching for frequently used data

### Passthrough Mode

Passthrough mode allows you to associate Suada conversations with your application's user system:

```typescript theme={null}
const suada = new Suada({
  apiKey: process.env.SUADA_API_KEY,
  passthroughMode: true
});

// When using passthrough mode, include externalUserIdentifier
const response = await suada.chat({
  message: "What's our revenue trend?",
  externalUserIdentifier: 'user-123'  // Required in passthrough mode
});
```

### Privacy Mode

Enable privacy mode to ensure sensitive information is handled with additional security:

```typescript theme={null}
const response = await suada.chat({
  message: "Analyze our financial data",
  privacyMode: true
});
```

## Error Handling

The SDK provides typed errors for better error handling:

```typescript theme={null}
import { Suada, SuadaError, SuadaAPIError } from '@suada/sdk';

try {
  const response = await suada.chat({
    message: "What's our revenue?"
  });
} catch (error) {
  if (error instanceof SuadaAPIError) {
    // Handle API-specific errors
    console.error('API Error:', error.message, error.status, error.code);
  } else if (error instanceof SuadaError) {
    // Handle general SDK errors
    console.error('SDK Error:', error.message);
  } else {
    // Handle unexpected errors
    console.error('Unexpected error:', error);
  }
}
```

## Best Practices

1. **Environment Variables**
   * Store API keys and sensitive configuration in environment variables
   * Use a package like `dotenv` to manage environment variables

2. **Error Handling**
   * Always implement try-catch blocks around API calls
   * Use the provided error types for specific error handling
   * Log errors appropriately for debugging

3. **TypeScript Usage**
   * Take advantage of built-in type definitions
   * Enable strict mode in your TypeScript configuration
   * Use type annotations for better code reliability

4. **Response Processing**
   * Always check for the presence of optional fields before using them
   * Handle missing data gracefully
   * Consider implementing retry logic for failed requests

## Configuration Options

| Option          | Type    | Required | Description                                                                                  |
| --------------- | ------- | -------- | -------------------------------------------------------------------------------------------- |
| apiKey          | string  | Yes      | Your Suada API key                                                                           |
| baseUrl         | string  | No       | Custom API endpoint (defaults to [https://suada.ai/api/public](https://suada.ai/api/public)) |
| passthroughMode | boolean | No       | Enable user-specific resources                                                               |

## FAQ

### How do I handle rate limiting?

The SDK automatically handles rate limiting by implementing exponential backoff. You can customize this behavior by implementing your own retry logic.

### Can I use the SDK in a browser environment?

No, the SDK is designed for server-side Node.js applications only. For browser applications, use our REST API with appropriate CORS headers.

### How do I maintain conversation context?

Use the `chatHistory` parameter to maintain conversation context:

```typescript theme={null}
const messages = [];
const response1 = await suada.chat({ message: "How's our revenue?" });
messages.push({ role: 'user', content: "How's our revenue?" });
messages.push({ role: 'assistant', content: response1.answer });

const response2 = await suada.chat({
  message: "Compare that to last year",
  chatHistory: messages
});
```

### How can I debug API calls?

Enable debug logging by setting the `DEBUG` environment variable:

```bash theme={null}
DEBUG=suada:* node your-app.js
```

### Support

* Email Support: [hello@suada.ai](mailto:hello@suada.ai)