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:
# 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:
// 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:
// 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:
import { environment } from './environments/environment';
@NgModule({
imports: [
SuadaModule.forRoot(environment.suada)
]
})
export class AppModule { }
Core Components
Chat Component
A pre-built chat interface component:
<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
Handle OAuth flows for third-party services:
<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:
<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:
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:
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:
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
- 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:
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:
: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:
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:
@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:
SuadaModule.forRoot({
apiKey: 'your-api-key',
debug: true
})
Support & Resources
Documentation
Support
