​
Overview

The Suada Vue SDK provides a seamless integration experience for Vue 3 applications. Built with the Composition API in mind, it offers components, composables, and utilities that follow Vue best practices while maintaining type safety through TypeScript.

​
Prerequisites

  • Vue 3.0.0 or higher
  • Node.js 16.0.0 or higher
  • A Suada API key
  • TypeScript 4.5+ (recommended)
  • Vite 3.0+ or Vue CLI 5.0+ (for development)

​
Installation

Install the Suada Vue SDK and its peer dependencies:

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

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

​
Quick Start

Here’s a basic example to get you started:

// main.ts
import { createApp } from 'vue';
import { createSuada } from '@suada/vue';
import App from './App.vue';

const app = createApp(App);

app.use(createSuada({
  apiKey: import.meta.env.VITE_SUADA_API_KEY
}));

app.mount('#app');

Create your first chat component:

<template>
  <SuadaChat
    placeholder="Ask a question..."
    :privacy-mode="true"
    @message-submit="onMessageSubmit"
    @response-received="onResponseReceived"
  />
</template>

<script setup lang="ts">
import { SuadaChat } from '@suada/vue';
import type { ChatMessage, ChatResponse } from '@suada/core';

const onMessageSubmit = (message: ChatMessage) => {
  console.log('Message sent:', message);
};

const onResponseReceived = (response: ChatResponse) => {
  console.log('Response:', response);
};
</script>

​
Authentication

​
Setting up your API Key

We recommend using environment variables with Vite:

# .env.development
VITE_SUADA_API_KEY=your-dev-key
VITE_SUADA_BASE_URL=https://dev-api.suada.ai

# .env.production
VITE_SUADA_API_KEY=your-prod-key
VITE_SUADA_BASE_URL=https://api.suada.ai

​
Plugin Configuration

Configure the plugin with environment-specific settings:

// suada.config.ts
import { type SuadaConfig } from '@suada/vue';

export const suadaConfig: SuadaConfig = {
  apiKey: import.meta.env.VITE_SUADA_API_KEY,
  baseUrl: import.meta.env.VITE_SUADA_BASE_URL,
  debug: import.meta.env.DEV
};

​
Core Components

​
Chat Component

A pre-built chat interface component:

<template>
  <SuadaChat
    theme="light"
    placeholder="Ask a question..."
    :initial-messages="messages"
    :privacy-mode="true"
    class="chat-container"
    @message-submit="onMessageSubmit"
    @response-received="onResponseReceived"
    @error="onError"
  >
    <template #input-prefix>
      <IconSend />
    </template>
    <template #empty-state>
      <p>Start a conversation!</p>
    </template>
  </SuadaChat>
</template>

​
Props

PropTypeRequiredDescription
theme’light’ | ‘dark’NoUI theme (defaults to ‘light’)
placeholderstringNoInput placeholder text
initialMessagesMessage[]NoPre-loaded chat messages
privacyModebooleanNoEnable enhanced privacy features
classstringNoAdditional CSS classes

​
Events

EventTypeDescription
messageSubmit(message: ChatMessage) => voidEmitted when a message is submitted
responseReceived(response: ChatResponse) => voidEmitted when a response is received
error(error: Error) => voidEmitted when an error occurs

​
Integration Components

​
Integration Manager

Manage service integrations:

<template>
  <SuadaIntegrationManager
    layout="grid"
    :filter="{ provider: 'notion' }"
    @integration-connected="onConnected"
    @integration-disconnected="onDisconnected"
  >
    <template #empty>
      <p>No integrations found</p>
    </template>
  </SuadaIntegrationManager>
</template>

<script setup lang="ts">
import { SuadaIntegrationManager } from '@suada/vue';
import type { Integration } from '@suada/core';

const onConnected = (integration: Integration) => {
  console.log(`${integration.provider} connected`);
};
</script>

​
Composables

​
useSuada

The main composable for accessing Suada functionality:

import { useSuada } from '@suada/vue';

const { 
  sendMessage,
  isLoading,
  error,
  messages
} = useSuada();

const handleSend = async () => {
  try {
    const response = await sendMessage({
      message: "What's the latest update?",
      privacyMode: true
    });
    console.log('Response:', response);
  } catch (error) {
    console.error('Error:', error);
  }
};

​
useIntegrations

Manage integrations programmatically:

import { useIntegrations } from '@suada/vue';

const {
  integrations,
  isConnecting,
  connect,
  disconnect
} = useIntegrations();

// Connect to a service
const handleConnect = async () => {
  try {
    await connect('notion', {
      redirectUri: 'https://your-app.com/callback'
    });
  } catch (error) {
    console.error('Error:', error);
  }
};

​
Error Handling

The SDK provides comprehensive error handling:

import { useSuada } from '@suada/vue';
import { SuadaError, SuadaAPIError } from '@suada/core';

const { sendMessage } = useSuada();

try {
  await sendMessage({ message: "Hello" });
} catch (error) {
  if (error instanceof SuadaAPIError) {
    // Handle API-specific errors
    console.error('API Error:', error.message, error.status);
  } 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

​
Security

  • Store API keys in environment variables
  • Use privacy mode for sensitive data
  • Implement proper error handling
  • Secure OAuth callback endpoints

​
Performance

  • Use proper cleanup in onUnmounted
  • Implement proper error boundaries
  • Use Vue’s built-in caching mechanisms
  • Optimize network requests

​
Development

  • Use TypeScript for better type safety
  • Follow Vue style guide
  • Write unit tests
  • Keep dependencies updated

​
FAQ

​
How do I handle environment-specific configuration?

Use Vite’s environment variables:

// suada.config.ts
export const suadaConfig = {
  apiKey: import.meta.env.VITE_SUADA_API_KEY,
  baseUrl: import.meta.env.VITE_SUADA_BASE_URL,
  debug: import.meta.env.DEV
};

​
How do I customize component themes?

Use CSS variables and custom classes:

<template>
  <SuadaChat class="custom-chat" />
</template>

<style>
:root {
  --suada-primary-color: #007bff;
  --suada-background-color: #ffffff;
  --suada-text-color: #333333;
}

.custom-chat {
  border-radius: 8px;
  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
}
</style>

​
How do I implement retry logic?

Configure retry behavior in the plugin:

app.use(createSuada({
  apiKey: import.meta.env.VITE_SUADA_API_KEY,
  maxRetries: 3,
  retryDelay: 1000
}));

​
How can I debug the SDK?

Enable debug mode in your configuration:

app.use(createSuada({
  apiKey: import.meta.env.VITE_SUADA_API_KEY,
  debug: true,
  logger: (message) => console.log('[Suada]', message)
}));

​
How do I use the SDK with Nuxt?

For Nuxt 3, create a plugin:

// plugins/suada.ts
export default defineNuxtPlugin((nuxtApp) => {
  const config = useRuntimeConfig();
  
  nuxtApp.vueApp.use(createSuada({
    apiKey: config.suadaApiKey
  }));
});

​
Support & Resources

​
Documentation

​
Community & Help

​
Contributing

We welcome contributions! See our Contributing Guide for details.