> ## 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.

# Vue SDK

> Learn how to integrate Suada with your Vue 3 application

## 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:

```bash theme={null}
# 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:

```typescript theme={null}
// 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:

```vue theme={null}
<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 theme={null}
# .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:

```typescript theme={null}
// 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:

```vue theme={null}
<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:

```vue theme={null}
<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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
// 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:

```vue theme={null}
<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:

```typescript theme={null}
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:

```typescript theme={null}
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:

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

## Support & Resources

### Documentation

* [API Reference](/api-reference)
* [Component Library](/components)
* [Integration Guides](/guides)
* [Vue Best Practices](/vue-best-practices)
* [Performance Guide](/performance)

### Community & Help

* GitHub Issues: [Report a bug](https://github.com/suada/vue-sdk/issues)
* Email Support: [support@suada.ai](mailto:support@suada.ai)
* Discord: [Join our community](https://discord.gg/suada)

### Contributing

We welcome contributions! See our [Contributing Guide](https://github.com/suada/vue-sdk/CONTRIBUTING.md) for details.