​
Overview

The Suada Vanilla JavaScript SDK provides a framework-agnostic way to integrate Suada’s AI capabilities into any web application. Built with modern JavaScript practices, it offers a lightweight, zero-dependency solution that works seamlessly in any browser environment.

​
Prerequisites

  • Modern browsers (Chrome 60+, Firefox 60+, Safari 12+, Edge 79+)
  • Node.js 16.0.0 or higher (for npm installation)
  • A Suada API key
  • Basic understanding of JavaScript and DOM manipulation

​
Installation

Choose the installation method that best suits your project:

​
NPM Installation

# Using npm
npm install @suada/vanilla @suada/core

# Using yarn
yarn add @suada/vanilla @suada/core

​
CDN Installation

Add the following script tag to your HTML: 
<script src="https://cdn.jsdelivr.net/npm/@suada/vanilla/dist/suada.min.js"></script>

​
Quick Start

Here’s a basic example to get you started: 
<!DOCTYPE html>
<html>
<head>
  <title>Suada Chat Example</title>
</head>
<body>
  <div id="chat-container"></div>

  <script src="https://cdn.jsdelivr.net/npm/@suada/vanilla/dist/suada.min.js"></script>
  <script>
    // Initialize Suada client
    const suada = new Suada.Client({
      apiKey: 'your-api-key'
    });

    // Create a chat instance
    const chat = new Suada.Chat({
      container: '#chat-container',
      onMessageSubmit: (message) => console.log('Message sent:', message),
      onResponseReceived: (response) => console.log('Response:', response)
    });

    // Initialize the chat
    chat.initialize();
  </script>
</body>
</html>

​
Authentication

​
Setting up your API Key

For development, you can use your API key directly: 
const client = new Suada.Client({
  apiKey: 'your-api-key'
});
For production, we recommend using environment variables: 
// Using webpack or similar bundler
import { config } from './config';

const client = new Suada.Client({
  apiKey: config.apiKey,
  environment: 'production'
});

​
Configuration Options

OptionTypeRequiredDescription
apiKeystringYesYour Suada API key
environment’development’ | ‘production’NoEnvironment setting (defaults to ‘development’)
baseUrlstringNoCustom API base URL
debugbooleanNoEnable debug logging
timeoutnumberNoRequest timeout in milliseconds

​
Core Components

​
Chat Component

A pre-built chat interface: 
const chat = new Suada.Chat({
  container: '#chat-container',
  theme: 'light',
  placeholder: 'Ask a question...',
  initialMessages: [],
  privacyMode: true,
  onMessageSubmit: (message) => {
    console.log('Message:', message);
  },
  onResponseReceived: (response) => {
    console.log('Response:', response);
  }
});

​
Options

OptionTypeRequiredDescription
containerstring | HTMLElementYesTarget container element or selector
theme’light’ | ‘dark’NoUI theme (defaults to ‘light’)
placeholderstringNoInput placeholder text
initialMessagesMessage[]NoPre-loaded chat messages
privacyModebooleanNoEnable enhanced privacy features

​
Integration Components

​
Integration Button

Create OAuth integration buttons: 
const button = new Suada.IntegrationButton({
  container: '#integration-button',
  provider: 'notion',
  redirectUri: 'https://your-app.com/callback',
  onSuccess: (result) => console.log('Connected:', result),
  onError: (error) => console.error('Error:', error)
});

​
Client API

​
Chat Methods

Send and receive messages: 
// Send a message
const response = await client.sendMessage({
  message: "What's the latest update?",
  privacyMode: true
});

// Get chat history
const history = await client.getChatHistory();

// Clear chat history
await client.clearChatHistory();

​
Integration Methods

Manage integrations programmatically: 
// Initialize OAuth flow
const authUrl = await client.initializeOAuth('notion', {
  redirectUri: 'https://your-app.com/callback'
});

// Handle OAuth callback
const result = await client.handleOAuthCallback({
  provider: 'notion',
  code: urlParams.get('code'),
  state: urlParams.get('state')
});

// List integrations
const integrations = await client.getIntegrations();

​
Error Handling

The SDK provides comprehensive error handling: 
try {
  await client.sendMessage({ message: "Hello" });
} catch (error) {
  if (error instanceof Suada.APIError) {
    // Handle API-specific errors
    console.error('API Error:', error.message, error.status);
  } else if (error instanceof Suada.NetworkError) {
    // Handle network-related errors
    console.error('Network Error:', error.message);
  } else {
    // Handle unexpected errors
    console.error('Unexpected error:', error);
  }
}

​
Styling

​
Using CSS Variables

Customize the appearance using CSS variables: 
:root {
  --suada-primary-color: #007bff;
  --suada-background-color: #ffffff;
  --suada-text-color: #333333;
  --suada-border-radius: 8px;
  --suada-font-family: system-ui, -apple-system, sans-serif;
}

​
Custom CSS Classes

Override default styles with custom classes: 
const chat = new Suada.Chat({
  container: '#chat-container',
  className: 'custom-chat',
  messageClassName: 'custom-message',
  inputClassName: 'custom-input'
});

​
Best Practices

​
Security

  • Store API keys securely
  • Implement proper CORS settings
  • Use privacy mode for sensitive data
  • Secure OAuth callback endpoints

​
Performance

  • Clean up components when not in use
  • Implement proper error handling
  • Use debouncing for user input
  • Optimize network requests

​
Development

  • Follow JavaScript best practices
  • Implement proper error boundaries
  • Use TypeScript for better type safety
  • Keep dependencies updated

​
FAQ

​
How do I handle CORS issues?

Configure your server to allow requests from your domain: 
const client = new Suada.Client({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.suada.ai',
  headers: {
    'Origin': window.location.origin
  }
});

​
How do I implement retry logic?

Configure retry behavior in the client: 
const client = new Suada.Client({
  apiKey: 'your-api-key',
  maxRetries: 3,
  retryDelay: 1000,
  retryCondition: (error) => error.status === 429
});

​
How do I handle rate limiting?

Implement exponential backoff: 
const client = new Suada.Client({
  apiKey: 'your-api-key',
  rateLimitConfig: {
    maxRetries: 3,
    initialDelay: 1000,
    maxDelay: 10000,
    backoffFactor: 2
  }
});

​
How can I debug the SDK?

Enable debug mode and use the logger: 
const client = new Suada.Client({
  apiKey: 'your-api-key',
  debug: true,
  logger: (message) => console.log('[Suada]', message)
});

​
How do I implement custom authentication?

Use the auth provider option: 
const client = new Suada.Client({
  apiKey: 'your-api-key',
  authProvider: async () => {
    const token = await getCustomToken();
    return { Authorization: `Bearer ${token}` };
  }
});

​
Support & Resources

​
Documentation

​
Support