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

# Angular SDK

> Learn how to integrate Suada with your Angular application

## Overview

The Suada Angular SDK provides a seamless way to integrate Suada's AI capabilities into your Angular applications. Built specifically for Angular 17+, it offers components, services, and utilities that follow Angular best practices and conventions.

## Prerequisites

* Angular 17.3.0 or higher
* Node.js 18.0.0 or higher
* A Suada API key
* npm or yarn package manager

## Installation

Install the Suada Angular SDK and its peer dependencies:

```bash theme={null}
# Using npm
npm install @suada/angular @suada/core

# Using yarn
yarn add @suada/angular @suada/core
```

## Quick Start

Here's a basic example to get you started:

```typescript theme={null}
// app.module.ts
import { NgModule } from '@angular/core';
import { SuadaModule } from '@suada/angular';

@NgModule({
  imports: [
    SuadaModule.forRoot({
      apiKey: 'your-api-key'
    })
  ]
})
export class AppModule { }

// app.component.ts
import { Component } from '@angular/core';
import { SuadaService } from '@suada/angular';

@Component({
  selector: 'app-root',
  template: `
    <div>
      <button (click)="sendMessage()">Ask Question</button>
      <p *ngIf="response">{{ response }}</p>
    </div>
  `
})
export class AppComponent {
  response?: string;

  constructor(private suada: SuadaService) {}

  async sendMessage() {
    try {
      const result = await this.suada.chat({
        message: "What insights can you provide?"
      });
      this.response = result.answer;
    } catch (error) {
      console.error('Error:', error);
    }
  }
}
```

## Authentication

### Setting up your API Key

We recommend storing your API key in environment files:

```typescript theme={null}
// environment.ts
export const environment = {
  production: false,
  suada: {
    apiKey: 'your-api-key'
  }
};

// environment.prod.ts
export const environment = {
  production: true,
  suada: {
    apiKey: process.env['SUADA_API_KEY']
  }
};
```

Then use it in your module:

```typescript theme={null}
import { environment } from './environments/environment';

@NgModule({
  imports: [
    SuadaModule.forRoot(environment.suada)
  ]
})
export class AppModule { }
```

## Core Components

### Chat Component

A pre-built chat interface component:

```html theme={null}
<suada-chat
  [theme]="'light'"
  [placeholder]="'Ask a question...'"
  (messageSubmit)="onMessageSubmit($event)"
  (responseReceived)="onResponseReceived($event)">
</suada-chat>
```

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

#### Events

| Event            | Type         | Description                       |
| ---------------- | ------------ | --------------------------------- |
| messageSubmit    | EventEmitter | Emitted when user sends a message |
| responseReceived | EventEmitter | Emitted when response is received |
| error            | EventEmitter | Emitted when an error occurs      |

### Integration Components

#### Integration Button

Handle OAuth flows for third-party services:

```html theme={null}
<suada-integration-button
  [provider]="'notion'"
  [redirectUri]="'https://your-app.com/callback'"
  (success)="onSuccess($event)"
  (error)="onError($event)">
  Connect Notion
</suada-integration-button>
```

#### Integration List

Display and manage integrated services:

```html theme={null}
<suada-integration-list
  [filter]="{ provider: 'notion' }"
  [layout]="'grid'"
  (select)="onSelect($event)"
  (delete)="onDelete($event)">
</suada-integration-list>
```

## Services

### SuadaService

The main service for interacting with Suada:

```typescript theme={null}
import { SuadaService } from '@suada/angular';

export class MyComponent {
  constructor(private suada: SuadaService) {}

  async sendMessage() {
    try {
      const response = await this.suada.chat({
        message: "What's our performance?",
        privacyMode: true
      });
      console.log(response.answer);
    } catch (error) {
      console.error('Error:', error);
    }
  }
}
```

### IntegrationService

Manage third-party integrations:

```typescript theme={null}
import { IntegrationService } from '@suada/angular';

export class MyComponent {
  constructor(private integrations: IntegrationService) {}

  async connectService() {
    try {
      const authUrl = await this.integrations.initializeOAuth('notion', {
        redirectUri: 'https://your-app.com/callback'
      });
      window.location.href = authUrl;
    } catch (error) {
      console.error('Error:', error);
    }
  }
}
```

## Error Handling

The SDK provides typed errors for better error handling:

```typescript theme={null}
import { SuadaError, SuadaAPIError } from '@suada/core';

try {
  await this.suada.chat({ 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 files
* Use privacy mode for sensitive data
* Implement proper error handling
* Secure OAuth callback endpoints

### Performance

* Reuse service instances
* Implement proper unsubscribe patterns
* Handle component lifecycle properly
* Consider implementing caching

### Development

* Use TypeScript strict mode
* Follow Angular style guide
* Write unit tests
* Keep dependencies updated

## FAQ

### How do I handle environment-specific configuration?

Use Angular's environment files and configure the module accordingly:

```typescript theme={null}
import { environment } from './environments/environment';

@NgModule({
  imports: [
    SuadaModule.forRoot({
      apiKey: environment.suada.apiKey,
      baseUrl: environment.suada.baseUrl
    })
  ]
})
```

### How do I customize the chat component theme?

You can override the default styles using CSS variables:

```scss theme={null}
:root {
  --suada-primary-color: #007bff;
  --suada-background-color: #ffffff;
  --suada-text-color: #333333;
}
```

### Can I use the SDK with SSR (Server-Side Rendering)?

Yes, the SDK is compatible with Angular Universal. Just ensure you handle the window object appropriately:

```typescript theme={null}
import { isPlatformBrowser } from '@angular/common';

constructor(
  @Inject(PLATFORM_ID) private platformId: Object
) {
  if (isPlatformBrowser(this.platformId)) {
    // Browser-only code
  }
}
```

### How do I implement retry logic?

The SDK includes built-in retry logic, but you can customize it:

```typescript theme={null}
@NgModule({
  imports: [
    SuadaModule.forRoot({
      apiKey: 'your-api-key',
      maxRetries: 3,
      retryDelay: 1000
    })
  ]
})
```

### How can I debug the SDK?

Enable debug mode in your environment configuration:

```typescript theme={null}
SuadaModule.forRoot({
  apiKey: 'your-api-key',
  debug: true
})
```

## Support & Resources

### Documentation

* [API Reference](/api-reference)
* [Component Library](/components)
* [Integration Guides](/guides)

### Support

* Email Support: [hello@suada.ai](mailto:hello@suada.ai)