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
• Chatbot Widget BFF: Threads, streaming, and auth via the Chatbot Widget backend (no direct LiteLLM or client-side permission filtering in this package)
• 💬 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

Pass env so the widget can call the Chatbot Widget BFF (threads, streaming). The widget obtains a JWT via same-origin POST /api/v1/tokens (session cookies), not a client-side secret. The BFF resolves the chatbot app from the authenticated session.

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

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

3. With Chatbot Widget BFF

The widget talks to the Chatbot Widget backend only. Auth uses the logged-in Superset session: the client calls same-origin POST /api/v1/tokens with credentials: 'include' (no client-side secret).

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

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

Access to databases and tables is enforced on the server; this package does not ship client-side permission helpers.

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 | | position | 'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left' | No | 'bottom-right' | Position of the floating button |

TypeScript Types

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

interface ChatbotWidgetConfig {
  env: Environment;
  position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
}

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:

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);
    };
  }, []);

  return (
    <div>
      <h1>My Application</h1>
      {/* Your app content */}
      
      <ChatbotWidget env="prod" 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