Vanilla JavaScript SDK

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

Option	Type	Required	Description
apiKey	string	Yes	Your Suada API key
environment	’development’ \| ‘production’	No	Environment setting (defaults to ‘development’)
baseUrl	string	No	Custom API base URL
debug	boolean	No	Enable debug logging
timeout	number	No	Request 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

Option	Type	Required	Description
container	string \| HTMLElement	Yes	Target container element or selector
theme	’light’ \| ‘dark’	No	UI theme (defaults to ‘light’)
placeholder	string	No	Input placeholder text
initialMessages	Message[]	No	Pre-loaded chat messages
privacyMode	boolean	No	Enable 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

Email Support: hello@suada.ai

Frontend SDKs

Backend SDKs

Overview

Prerequisites

Installation

NPM Installation

CDN Installation

Quick Start

Authentication

Setting up your API Key

Configuration Options

Core Components

Chat Component

Options

Integration Components

Integration Button

Client API

Chat Methods

Integration Methods

Error Handling

Styling

Using CSS Variables

Custom CSS Classes

Best Practices

Security

Performance

Development

FAQ

How do I handle CORS issues?

How do I implement retry logic?

How do I handle rate limiting?

How can I debug the SDK?

How do I implement custom authentication?

Support & Resources

Documentation

Support

​Overview

​Prerequisites

​Installation

​NPM Installation

​CDN Installation

​Quick Start

​Authentication

​Setting up your API Key

​Configuration Options

​Core Components

​Chat Component

​Options

​Integration Components

​Integration Button

​Client API

​Chat Methods

​Integration Methods

​Error Handling

​Styling

​Using CSS Variables

​Custom CSS Classes

​Best Practices

​Security

​Performance

​Development

​FAQ

​How do I handle CORS issues?

​How do I implement retry logic?

​How do I handle rate limiting?

​How can I debug the SDK?

​How do I implement custom authentication?

​Support & Resources

​Documentation

​Support

Overview

Prerequisites

Installation

NPM Installation

CDN Installation

Quick Start

Authentication

Setting up your API Key

Configuration Options

Core Components

Chat Component

Options

Integration Components

Integration Button

Client API

Chat Methods

Integration Methods

Error Handling

Styling

Using CSS Variables

Custom CSS Classes

Best Practices

Security

Performance

Development

FAQ

How do I handle CORS issues?

How do I implement retry logic?

How do I handle rate limiting?

How can I debug the SDK?

How do I implement custom authentication?

Support & Resources

Documentation

Support