React SDK

Overview

The Suada React SDK provides a seamless way to integrate Suada’s AI capabilities into your React applications. Built with modern React practices in mind, it offers hooks, components, and utilities that make it easy to add AI-powered features to your application.

Prerequisites

React 16.8.0 or higher (for Hooks support)
Node.js 16.0.0 or higher
A Suada API key
npm or yarn package manager

Installation

Install the Suada React SDK and its peer dependencies:

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

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

Quick Start

Here’s a basic example to get you started:

import { SuadaProvider, ChatComponent } from '@suada/react';

function App() {
  return (
    <SuadaProvider
      config={{
        apiKey: process.env.REACT_APP_SUADA_API_KEY
      }}
    >
      <ChatComponent
        onMessageSubmit={(message) => console.log('Message sent:', message)}
        onResponseReceived={(response) => console.log('Response:', response)}
      />
    </SuadaProvider>
  );
}

Authentication

Setting up your API Key

We recommend storing your API key in environment variables:

# .env.local
REACT_APP_SUADA_API_KEY=your-api-key

For production, ensure you’re using appropriate environment configuration:

# .env.production
REACT_APP_SUADA_API_KEY=your-production-api-key
REACT_APP_SUADA_BASE_URL=https://api.suada.ai

Configuring the Provider

Wrap your application with SuadaProvider:

import { SuadaProvider } from '@suada/react';

function App() {
  return (
    <SuadaProvider
      config={{
        apiKey: process.env.REACT_APP_SUADA_API_KEY,
        baseUrl: process.env.REACT_APP_SUADA_BASE_URL,
        debug: process.env.NODE_ENV === 'development'
      }}
    >
      <YourApp />
    </SuadaProvider>
  );
}

Core Components

Chat Component

A pre-built chat interface component:

import { ChatComponent } from '@suada/react';

function ChatInterface() {
  return (
    <ChatComponent
      theme="light"
      placeholder="Ask a question..."
      initialMessages={[]}
      privacyMode={true}
      onMessageSubmit={(message) => {
        console.log('Message:', message);
      }}
      onResponseReceived={(response) => {
        console.log('Response:', response);
      }}
    />
  );
}

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
onMessageSubmit	(message: string) => void	Yes	Called when a message is submitted
onResponseReceived	(response: Response) => void	Yes	Called when a response is received
onError	(error: Error) => void	No	Called when an error occurs

Integration Components

Integration Manager

The main component for managing integrations:

import { IntegrationManager } from '@suada/react';

function IntegrationsPage() {
  return (
    <IntegrationManager
      onIntegrationConnected={(integration) => {
        console.log(`${integration.provider} connected`);
      }}
      onIntegrationDisconnected={(integration) => {
        console.log(`${integration.provider} disconnected`);
      }}
      layout="grid"
      className="custom-integration-manager"
    />
  );
}

Integration Button

A standalone button for connecting services:

import { IntegrationButton } from '@suada/react';

function ConnectButton() {
  return (
    <IntegrationButton
      provider="notion"
      redirectUri="https://your-app.com/callback"
      onSuccess={(result) => console.log('Connected:', result)}
      onError={(error) => console.error('Error:', error)}
    />
  );
}

Hooks

useSuada

The main hook for accessing Suada functionality:

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

function ChatFeature() {
  const { sendMessage, isLoading, error } = 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);
    }
  };

  return (
    <div>
      <button onClick={handleSend} disabled={isLoading}>
        Send Message
      </button>
      {error && <p>Error: {error.message}</p>}
    </div>
  );
}

useIntegrations

Manage integrations programmatically:

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

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

  return (
    <div>
      {integrations.map((integration) => (
        <div key={integration.id}>
          <span>{integration.provider}</span>
          <button 
            onClick={() => disconnect(integration.id)}
            disabled={isConnecting}
          >
            Disconnect
          </button>
        </div>
      ))}
    </div>
  );
}

Error Handling

The SDK provides typed errors for better error handling:

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

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 boundaries
Secure OAuth callback endpoints

Performance

Implement proper cleanup in useEffect
Use memoization for expensive computations
Implement proper error boundaries
Consider implementing request caching

Development

Use TypeScript for better type safety
Follow React best practices
Write unit tests
Keep dependencies updated

FAQ

How do I handle environment-specific configuration?

Use environment files and ensure they’re properly configured:

# .env.development
REACT_APP_SUADA_API_KEY=your-dev-key
REACT_APP_SUADA_BASE_URL=https://dev-api.suada.ai

# .env.production
REACT_APP_SUADA_API_KEY=your-prod-key
REACT_APP_SUADA_BASE_URL=https://api.suada.ai

How do I customize component themes?

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 Next.js?

Yes, the SDK is compatible with Next.js. For server components, use the appropriate imports:

'use client';
import { SuadaProvider } from '@suada/react';

How do I implement retry logic?

The SDK includes built-in retry logic that you can configure:

<SuadaProvider
  config={{
    apiKey: process.env.REACT_APP_SUADA_API_KEY,
    maxRetries: 3,
    retryDelay: 1000
  }}
>
  <YourApp />
</SuadaProvider>

How can I debug the SDK?

Enable debug mode in your provider configuration:

<SuadaProvider
  config={{
    apiKey: process.env.REACT_APP_SUADA_API_KEY,
    debug: true
  }}
>
  <YourApp />
</SuadaProvider>

Support & Resources

Documentation

Support

Email Support: hello@suada.ai

Frontend SDKs

Backend SDKs

Overview

Prerequisites

Installation

Quick Start

Authentication

Setting up your API Key

Configuring the Provider

Core Components

Chat Component

Props

Integration Components

Integration Manager

Integration Button

Hooks

useSuada

useIntegrations

Error Handling

Best Practices

Security

Performance

Development

FAQ

How do I handle environment-specific configuration?

How do I customize component themes?

Can I use the SDK with Next.js?

How do I implement retry logic?

How can I debug the SDK?

Support & Resources

Documentation

Support

​Overview

​Prerequisites

​Installation

​Quick Start

​Authentication

​Setting up your API Key

​Configuring the Provider

​Core Components

​Chat Component

​Props

​Integration Components

​Integration Manager

​Integration Button

​Hooks

​useSuada

​useIntegrations

​Error Handling

​Best Practices

​Security

​Performance

​Development

​FAQ

​How do I handle environment-specific configuration?

​How do I customize component themes?

​Can I use the SDK with Next.js?

​How do I implement retry logic?

​How can I debug the SDK?

​Support & Resources

​Documentation

​Support

Overview

Prerequisites

Installation

Quick Start

Authentication

Setting up your API Key

Configuring the Provider

Core Components

Chat Component

Props

Integration Components

Integration Manager

Integration Button

Hooks

useSuada

useIntegrations

Error Handling

Best Practices

Security

Performance

Development

FAQ

How do I handle environment-specific configuration?

How do I customize component themes?

Can I use the SDK with Next.js?

How do I implement retry logic?

How can I debug the SDK?

Support & Resources

Documentation

Support