Text to SQL Chatbot Widget

A React component library for integrating a Text to SQL chatbot widget into your React applications. This widget provides a floating button that opens a chat interface where users can generate SQL queries from natural language.

Features

• 🎨 Framework-agnostic: Works with React 16.13.1+ (React is a peer dependency)
• 🔌 Easy Integration: Simple integration with any React application
• 🔒 Permission Support: Built-in permission filtering for database/table access
• 💬 Chat Interface: Modern chat UI with message history and drag-to-move functionality
• 📋 SQL Display: Formatted SQL query display with copy and insert actions
• 🎯 Event-based: CustomEvent API for loose coupling with host applications

Installation

npm install teko-text2sql-chatbot-widget

or with yarn:

yarn add teko-text2sql-chatbot-widget

Quick Start

1. Import the Component and CSS

import React from 'react';
import { ChatbotWidget } from 'teko-text2sql-chatbot-widget';
// Don't forget to import the CSS!
import 'teko-text2sql-chatbot-widget/dist/index.css';

function App() {
  return (
    <div>
      {/* Your app content */}
      <ChatbotWidget 
        env="prod"
      />
    </div>
  );
}

2. Basic Usage

The simplest usage only requires an env prop:

import { ChatbotWidget } from 'teko-text2sql-chatbot-widget';
import 'teko-text2sql-chatbot-widget/dist/index.css';

function MyApp() {
  return (
    <ChatbotWidget 
      env="prod"
    />
  );
}

3. With Permissions

To filter database schemas based on user permissions:

import { ChatbotWidget } from 'teko-text2sql-chatbot-widget';
import 'teko-text2sql-chatbot-widget/dist/index.css';

function MyApp() {
  const getUserPermissions = async () => {
    // Fetch or return user permissions
    return {
      datasource_access: [
        '[analytics_db].[public].[orders]',
        '[analytics_db].[public].[users]',
      ],
      database_access: ['analytics_db'],
      schema_access: ['[analytics_db].[public]'],
    };
  };

  return (
    <ChatbotWidget 
      env="prod"
      getUserPermissions={getUserPermissions}
    />
  );
}

4. With User ID

To identify the user making SQL generation requests:

import { ChatbotWidget } from 'teko-text2sql-chatbot-widget';
import 'teko-text2sql-chatbot-widget/dist/index.css';

function MyApp() {
  const currentUserId = 'user_12345'; // Get from your auth system

  return (
    <ChatbotWidget 
      env="prod"
      userId={currentUserId}
    />
  );
}

Environment Configuration

The env prop determines which API endpoint the widget will use:

• "dev" - Development environment: https://dev-api.text2sql.com
• "stag" - Staging environment: https://stag-api.text2sql.com
• "prod" - Production environment: https://api.text2sql.com

Example:

// Development
<ChatbotWidget env="dev" />

// Staging
<ChatbotWidget env="stag" />

// Production
<ChatbotWidget env="prod" />

API Reference

ChatbotWidget Props

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | env | 'dev' \| 'stag' \| 'prod' | Yes | - | Environment: 'dev' for development, 'stag' for staging, 'prod' for production | | getUserPermissions | () => Promise<Permissions> \| Permissions | No | - | Function to get user permissions | | position | 'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left' | No | 'bottom-right' | Position of the floating button | | userId | string | No | - | User ID to identify the user making the SQL generation request |

TypeScript Types

type Environment = 'dev' | 'stag' | 'prod';

interface ChatbotWidgetConfig { env: Environment; getUserPermissions?: () => Promise | Permissions; position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'; userId?: string; }

interface Permissions { datasource_access?: string[]; // Format: '[database_name].[schema].[table_name]' database_access?: string[]; schema_access?: string[]; // Format: '[database_name].[schema]' catalog_access?: string[]; }

## Advanced Usage

### Handling Query Insertion with Custom Events

The widget uses CustomEvents to notify your application when a user wants to insert a SQL query. Listen for the `chatbot:insert-query` event:

```tsx
import { ChatbotWidget } from 'teko-text2sql-chatbot-widget';
import 'teko-text2sql-chatbot-widget/dist/index.css';

function MyApp() {
  React.useEffect(() => {
    const handleInsertQuery = (event: CustomEvent) => {
      const { query } = event.detail;
      // Insert query into your application
      insertSQLIntoEditor(query);
    };

    window.addEventListener('chatbot:insert-query', handleInsertQuery as EventListener);
    return () => {
      window.removeEventListener('chatbot:insert-query', handleInsertQuery as EventListener);
    };
  }, []);

  return (
    <ChatbotWidget
      env="prod"
    />
  );
}

Complete Example with All Features

import React, { useEffect } from 'react';
import { ChatbotWidget } from 'teko-text2sql-chatbot-widget';
import 'teko-text2sql-chatbot-widget/dist/index.css';

function MyApp() {
  // Listen for query insertion events
  useEffect(() => {
    const handleInsertQuery = (event: CustomEvent) => {
      const { query } = event.detail;
      // Insert SQL into your query editor
      insertSQLIntoEditor(query);
    };

    window.addEventListener('chatbot:insert-query', handleInsertQuery as EventListener);
    return () => {
      window.removeEventListener('chatbot:insert-query', handleInsertQuery as EventListener);
    };
  }, []);

  const getUserPermissions = async () => {
    // Fetch from your backend
    const response = await fetch('/api/permissions');
    return response.json();
  };

  const currentUserId = 'user_12345'; // Get from your auth system

  return (
    <div>
      <h1>My Application</h1>
      {/* Your app content */}
      
      <ChatbotWidget
        env="prod"
        userId={currentUserId}
        getUserPermissions={getUserPermissions}
        position="bottom-right"
      />
    </div>
  );
}

Styling

The widget comes with its own CSS that must be imported. The widget uses a light theme by default with a cyan gradient color scheme.

Custom Styling

You can override the widget styles by targeting the CSS classes:

• .floating-button - The floating action button
• .chat-window - The chat window container
• .message-item - Individual chat messages
• .sql-display - SQL query display block

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Requirements

• React 16.13.1 or higher
• React DOM 16.13.1 or higher

Bundle Size

With externalized React, the bundle size is approximately ~20KB gzipped, making it lightweight and suitable for production use.

License

MIT