​
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

PropTypeRequiredDescription
theme’light’ | ‘dark’NoUI theme (defaults to ‘light’)
placeholderstringNoInput placeholder text
initialMessagesMessage[]NoPre-loaded chat messages
privacyModebooleanNoEnable enhanced privacy features
onMessageSubmit(message: string) => voidYesCalled when a message is submitted
onResponseReceived(response: Response) => voidYesCalled when a response is received
onError(error: Error) => voidNoCalled 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