@mravatech/figo-react-native-sdk

v1.0.2

Published

a year ago

React Native SDK for Figo AI's embed functionality

0High
0Medium
0Low

mravatech

react-native expo figo-ai data-analysis ai sdk embed chat analytics

Figo AI React Native SDK

A production-grade React Native SDK for integrating Figo AI's data analysis and visualization capabilities into mobile applications.

✨ Features

🔐 Secure Authentication: JWT-based token management with automatic refresh
💬 Conversation Management: Create, list, and manage AI conversations
📨 Message Services: Send queries and receive AI-powered responses
📊 Analytics: Built-in usage tracking and performance monitoring
🚀 Real-time Streaming: Server-sent events for live data updates
⚛️ React Hooks: Modern hooks API for seamless React Native integration
💾 Offline Support: Local caching with intelligent synchronization
🔒 Enterprise Security: Keychain/Keystore integration for sensitive data
📱 Expo Compatible: Full support for Expo with development builds

📱 Platform Support

✅ React Native 0.60+
✅ Expo SDK 48+ (with development builds)
✅ iOS 12.0+
✅ Android API 21+ (Android 5.0+)

💡 Using Expo? See our Expo Setup Guide for detailed instructions.

Installation

📱 Expo Users: Follow the Expo Setup Guide instead of the instructions below.

1. Install the SDK and Peer Dependencies

npm install @figo-ai/react-native-sdk

# Install required peer dependencies (native modules)
npm install @react-native-async-storage/async-storage \
  @react-native-community/netinfo \
  react-native-keychain \
  react-native-reanimated \
  react-native-safe-area-context \
  react-native-svg

# or with yarn
yarn add @figo-ai/react-native-sdk \
  @react-native-async-storage/async-storage \
  @react-native-community/netinfo \
  react-native-keychain \
  react-native-reanimated \
  react-native-safe-area-context \
  react-native-svg

2. Configure react-native-reanimated

Add the plugin to your babel.config.js:

module.exports = {
  presets: ['module:@react-native/babel-preset'],
  plugins: ['react-native-reanimated/plugin'], // Add this line
};

3. iOS Setup

cd ios && pod install && cd ..

4. Android Setup

No additional setup required - auto-linking handles everything!

5. Rebuild Your App

# Clear cache and restart
npm start -- --reset-cache

# In another terminal, run:
npx react-native run-ios
# or
npx react-native run-android

Quick Start

Option 1: With UI Components (Recommended - Just 3 Lines!)

import { FigoProvider, ChatInterface } from '@figo-ai/react-native-sdk';

export default function App() {
  return (
    <FigoProvider
      config={{
        apiKey: 'your-api-key',
        customerId: 'customer-123',
        connectionId: 'postgres-prod',
      }}
    >
      <ChatInterface />
    </FigoProvider>
  );
}

That's it! You now have a complete chat interface with:

✅ Real-time streaming
✅ Offline support
✅ Analytics tracking
✅ Message history
✅ Connection status
✅ Error handling

Option 2: With Core Client (Programmatic)

import { FigoClient } from '@figo-ai/react-native-sdk';

// Initialize the SDK
const client = new FigoClient({
  apiKey: 'your-api-key',
  customerId: 'customer-123',
  connectionId: 'connection-456',
  baseUrl: 'https://api.figo.ai', // Optional
  enableAnalytics: true,           // Optional
  debugMode: false,                // Optional
});

// Initialize and authenticate
await client.initialize();

// Check authentication status
const isAuthenticated = await client.isAuthenticated();
console.log('Authenticated:', isAuthenticated);

Configuration

Required Parameters

apiKey: Your Figo AI API key
customerId: Unique customer identifier
connectionId: Database connection identifier

Optional Parameters

baseUrl: API base URL (default: https://api.figo.ai)
enableAnalytics: Enable usage analytics (default: true)
enableOfflineMode: Enable offline support (default: false)
debugMode: Enable debug logging (default: false)
requestTimeout: Request timeout in ms (default: 30000)
maxRetries: Max retry attempts (default: 3)

Core Services

Conversation Service

Manage AI conversations with full CRUD operations:

// Create a conversation
const conversation = await client.conversations.create({
  name: 'Sales Analysis',
  initial_message: 'Show me Q4 sales data',
});

// List conversations
const list = await client.conversations.list({
  limit: 10,
  sort_by: 'created_at',
});

// Get suggestions
const suggestions = await client.conversations.getSuggestions(conversation.id);

Message Service

Send queries and handle AI responses:

// Send a query
const response = await client.messages.sendQuery(conversation.id, {
  query: 'What are the top 10 customers by revenue?',
  options: {
    execute_query: true,
    generate_charts: true,
  },
});

// Process results
response.ai_message.results?.forEach(result => {
  switch (result.type) {
    case 'SQL_QUERY_STRING_RESULT':
      console.log('SQL:', result.content.sql);
      break;
    case 'CHART_GENERATION_RESULT':
      console.log('Chart:', result.content.chart_type);
      break;
  }
});

Analytics Service

Track usage and performance metrics:

// Track events
await client.analytics?.track('QUERY_EXECUTED', {
  duration: 1250,
  success: true,
});

// Get analytics summary
const summary = await client.analytics?.getSummary({
  start_date: '2024-01-01',
  end_date: '2024-12-31',
});

Core Components

Token Management

The SDK automatically handles token generation, storage, and refresh:

// Token is automatically managed
const tokenManager = client.getTokenManager();

// Check if authenticated
const isAuth = await tokenManager.isAuthenticated();

// Manual token refresh (usually not needed)
await tokenManager.refreshToken();

// Logout
await client.logout();

React Hooks

The SDK provides modern React hooks for seamless integration:

useFigoSDK - All-in-One Hook

import { useFigoSDK } from '@figo-ai/react-native-sdk';

function ChatScreen() {
  const sdk = useFigoSDK({
    apiKey: 'your-api-key',
    customerId: 'customer-123',
    connectionId: 'postgres-prod',
  });

  const { conversation, streaming, messages, actions } = sdk;

  // Use quick actions
  const handleSend = async (query: string) => {
    await actions.streamQuery(query);
  };

  return (
    <View>
      {streaming.isStreaming && <ActivityIndicator />}
      {streaming.results.map(result => (
        <ResultView key={result.id} result={result} />
      ))}
    </View>
  );
}

Individual Hooks

useFigoClient: Initialize and manage SDK client
useConversation: Manage conversations with state
useStreaming: Real-time streaming with progress
useMessages: Message handling with caching
useAnalytics: Event and performance tracking
useOffline: Offline support with queue management

UI Components

The SDK includes ready-to-use React Native components:

FigoProvider

Context provider that wraps your app:

<FigoProvider
  config={{
    apiKey: 'your-api-key',
    customerId: 'customer-123',
    connectionId: 'postgres-prod',
  }}
  options={{
    conversation: { autoLoad: true },
    streaming: { trackMetrics: true },
    analytics: { autoStart: true },
    offline: { autoSync: true },
  }}
  loadingComponent={<LoadingScreen />}
  errorComponent={(error) => <ErrorScreen error={error} />}
>
  <YourApp />
</FigoProvider>

ChatInterface

Complete chat UI with all features:

<ChatInterface
  showConnectionStatus
  showConversationHeader
  enableVoiceInput={false}
  enableAttachments={false}
  theme={{
    primaryColor: '#6366F1',
    backgroundColor: '#F9FAFB',
    textColor: '#111827',
  }}
  onMessageSent={(query) => console.log('Sent:', query)}
  onError={(error) => console.error(error)}
/>

Individual Components

Build your own UI with granular components:

import {
  MessageList,
  QueryInput,
  ResultViewer,
  ConnectionStatusIndicator,
  LoadingOverlay,
} from '@figo-ai/react-native-sdk';

// Custom chat screen
function CustomChat() {
  const { messages, streaming } = useFigo();
  
  return (
    <>
      <MessageList messages={messages.messages} />
      <QueryInput onSend={handleSend} />
      {streaming.isStreaming && <LoadingOverlay />}
    </>
  );
}

Available Components

FigoProvider - Context provider for SDK
ChatInterface - Complete chat interface
MessageList - Display messages with results
QueryInput - Smart input with suggestions
ResultViewer - Display SQL results, charts, tables
ChartRenderer - Render data visualizations
ConnectionStatusIndicator - Network status
LoadingOverlay - Loading states
MessageSkeleton - Skeleton loaders

API Client

Make authenticated API requests:

const apiClient = client.getApiClient();

// GET request
const response = await apiClient.get('/embed/conversations');

// POST request
const newConversation = await apiClient.post('/embed/conversation', {
  name: 'Sales Analysis',
});

Error Handling

The SDK provides custom error classes for different scenarios:

import { 
  AuthenticationError,
  RateLimitError,
  NetworkError,
  ValidationError 
} from '@figo-ai/react-native-sdk';

try {
  await client.initialize();
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Authentication failed:', error.message);
  } else if (error instanceof RateLimitError) {
    console.error('Rate limited. Retry after:', error.retryAfter);
  } else if (error instanceof NetworkError) {
    console.error('Network error:', error.message);
  }
}

Rate Limiting

Built-in client-side rate limiting prevents hitting server limits:

// Rate limits are automatically enforced
// Default limits:
// - Token generation: 10/hour
// - Conversations: 100/hour
// - Queries: 1000/hour

Security

Secure Storage

Sensitive data is stored securely using platform-specific solutions:

iOS: Keychain Services
Android: Android Keystore

Encryption

All local data is encrypted using AES-256 encryption.

Development

Building

npm run build

Testing

npm test
npm run test:watch
npm run test:coverage

Linting

npm run lint
npm run format

Architecture

@figo-ai/react-native-sdk/
├── src/
│   ├── core/           # Core SDK functionality
│   │   ├── client/     # Main SDK client
│   │   ├── auth/       # Authentication & token management
│   │   └── config/     # Configuration
│   ├── utils/          # Utility functions
│   │   ├── Errors.ts   # Custom error classes
│   │   └── RateLimiter.ts # Rate limiting
│   └── index.ts        # Package exports

Performance

Initial load: < 2 seconds
Token generation: < 500ms
API response: < 100ms (p95)
Memory usage: < 50MB baseline

Requirements

React Native >= 0.60.0
React >= 16.8.0
iOS 11.0+
Android 5.0+ (API 21+)

Support

For issues and questions, please contact [email protected]

License

MIT © Figo AI

Roadmap

Phase 1: Core Foundation ✅

[x] Token management
[x] Secure storage
[x] API client
[x] Error handling
[x] Rate limiting

Phase 2: Services (Coming Soon)

[ ] Conversation management
[ ] Message handling
[ ] Analytics tracking
[ ] Connection management

Phase 3: Streaming (Coming Soon)

[ ] SSE client
[ ] Real-time updates
[ ] Result processing

Phase 4: UI Components (Coming Soon)

[ ] Chat interface
[ ] Message list
[ ] Result displays
[ ] Theming system

Phase 5: Advanced Features (Coming Soon)

[ ] Offline support
[ ] Voice input
[ ] File attachments
[ ] Custom components

Contributing

We welcome contributions! Please see our contributing guidelines for details.

Changelog

Version 1.0.0

Initial release
Core authentication system
Secure token management
API client with interceptors
Rate limiting
Error handling