Vue SDK

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

Prop	Type	Required	Description
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
class	string	No	Additional CSS classes

Events

Event	Type	Description
messageSubmit	(message: ChatMessage) => void	Emitted when a message is submitted
responseReceived	(response: ChatResponse) => void	Emitted when a response is received
error	(error: Error) => void	Emitted 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
  }));
});

Frontend SDKs

Backend SDKs

Overview

Prerequisites

Installation

Quick Start

Authentication

Setting up your API Key

Plugin Configuration

Core Components

Chat Component

Props

Events

Integration Components

Integration Manager

Composables

useSuada

useIntegrations

Error Handling

Best Practices

Security

Performance

Development

FAQ

How do I handle environment-specific configuration?

How do I customize component themes?

How do I implement retry logic?

How can I debug the SDK?

How do I use the SDK with Nuxt?

Support & Resources

Documentation

Community & Help

Contributing

​Overview

​Prerequisites

​Installation

​Quick Start

​Authentication

​Setting up your API Key

​Plugin Configuration

​Core Components

​Chat Component

​Props

​Events

​Integration Components

​Integration Manager

​Composables

​useSuada

​useIntegrations

​Error Handling

​Best Practices

​Security

​Performance

​Development

​FAQ

​How do I handle environment-specific configuration?

​How do I customize component themes?

​How do I implement retry logic?

​How can I debug the SDK?

​How do I use the SDK with Nuxt?

​Support & Resources

​Documentation

​Community & Help

​Contributing

Overview

Prerequisites

Installation

Quick Start

Authentication

Setting up your API Key

Plugin Configuration

Core Components

Chat Component

Props

Events

Integration Components

Integration Manager

Composables

useSuada

useIntegrations

Error Handling

Best Practices

Security

Performance

Development

FAQ

How do I handle environment-specific configuration?

How do I customize component themes?

How do I implement retry logic?

How can I debug the SDK?

How do I use the SDK with Nuxt?

Support & Resources

Documentation

Community & Help

Contributing