> ## 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.
# Vanilla JavaScript SDK
> Learn how to integrate Suada with vanilla JavaScript applications
## 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
```bash theme={null}
# 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:
```html theme={null}
```
## Quick Start
Here's a basic example to get you started:
```html theme={null}
Suada Chat Example
```
## Authentication
### Setting up your API Key
For development, you can use your API key directly:
```javascript theme={null}
const client = new Suada.Client({
apiKey: 'your-api-key'
});
```
For production, we recommend using environment variables:
```javascript theme={null}
// 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:
```javascript theme={null}
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:
```javascript theme={null}
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:
```javascript theme={null}
// 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:
```javascript theme={null}
// 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:
```javascript theme={null}
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:
```css theme={null}
: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:
```javascript theme={null}
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:
```javascript theme={null}
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:
```javascript theme={null}
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:
```javascript theme={null}
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:
```javascript theme={null}
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:
```javascript theme={null}
const client = new Suada.Client({
apiKey: 'your-api-key',
authProvider: async () => {
const token = await getCustomToken();
return { Authorization: `Bearer ${token}` };
}
});
```
## Support & Resources
### Documentation
* [API Reference](/api-reference)
* [Component Library](/components)
* [Integration Guides](/guides)
* [Security Guide](/security)
* [Performance Guide](/performance)
### Support
* Email Support: [hello@suada.ai](mailto:hello@suada.ai)