DocGinie AI Analytics

A standalone, powerful React component package for an AI-powered analytics chat and dashboard interface. Easily integrate a full ChatGPT-like AI analytics experience into any React application.

Features

• Conversational Analytics (Chat): Chat interface for querying data, rendering dynamic charts, tables, and insights.
• Interactive Dashboards (Dashboard): Save charts and insights to a customizable drag-and-drop dashboard grid.
• Read-Only Dashboard Viewer (DashboardViewer): View-only dashboard component for embedding in reports, presentations, or public pages - no editing capabilities.
• External Dashboard Sharing (ExternalDashboardAuth, ExternalDashboardViewer): Securely share dashboards externally via password-protected links.
• Dark Mode Support: Built-in light and dark modes with customizable CSS parameters.
• Session Management: Rename, pin, delete, and switch between chat sessions.
• Optimized Data Fetching: Internal lightweight hooks and isolated API clients to prevent polluting your host application's state.

Installation

npm install docginie-ai-analytics

Peer Dependencies

Make sure these are installed in your host project:

npm install react react-dom antd echarts echarts-for-react axios @ant-design/icons react-markdown

Quick Start

1. Configure the API URL (Required)

You MUST provide the API URL using an environment variable from your host application. The package will throw a critical error if this configuration is missing.

Call configureDocGinie once at your app's entry point (e.g., main.jsx or App.jsx):

import { configureDocGinie } from 'docginie-ai-analytics';

// Webpack/CRA:
configureDocGinie({
  apiUrl: process.env.REACT_APP_DOC_GINIE_API_URL,
  axiosTimeout: 60000, // optional, 60s (default: 30s)
});

// Vite:
// configureDocGinie({
//   apiUrl: import.meta.env.VITE_DOC_GINIE_API_URL,
//   axiosTimeout: 60000,
// });

2. Authenticate

Authenticate and store the JWT token before rendering the analytics interface:

import { loginDocGinie } from 'docginie-ai-analytics';

// Option A: Pass a pre-existing JWT token directly
await loginDocGinie({ token: 'your-jwt-token-here' });

// Option B: Login via DocGinie auth API using authCode and userId
await loginDocGinie({ authCode: 'your-auth-code', userId: 'user-123' });

3. Render the Main Component

import { AiAnalytics } from 'docginie-ai-analytics';
import 'docginie-ai-analytics/dist/esm/styles.css';

function MyAnalyticsPage() {
  return (
    <div style={{ height: '100vh' }}>
      <AiAnalytics defaultView="chat" />
    </div>
  );
}

API & Components Reference

Configuration & Auth API

configureDocGinie(config)

Sets the base API URL globally. Call once before rendering any components.

• config.apiUrl (string, required): The DocGinie AI Analytics API base URL.
• config.getAuthToken (function, optional): A callback function that returns the auth token, overriding internal localStorage.
• config.axiosTimeout (number, optional): Request timeout in milliseconds. Defaults to 30000 (30 seconds).

loginDocGinie(params)

Authenticates and stores the token internally.

• params.token (string): Pre-existing JWT token (skips API call).
• params.authCode (string): Auth-Code header value.
• params.userId (string): User-Id header value.
• params.apiUrl (string): Override API URL for this call only.

logoutDocGinie()

Removes the stored token from localStorage.

isDocGinieAuthenticated()

Returns true if a token exists in localStorage.

React Components

<AiAnalytics />

The main wrapper component that handles switching between the Chat and Dashboard views, alongside built-in error handling for missing configurations.

| Prop | Type | Default | Description | | ----------------- | ----------------------- | -------- | -------------------------------------------------------------------------------------- | | apiUrl | string | optional | Override the global API URL for this specific instance. | | defaultView | 'chat' \| 'dashboard' | 'chat' | The initial view to render. | | darkMode | boolean | optional | Optional prop to control dark mode externally. If provided, hides the internal toggle. | | showShareButton | boolean | true | Controls whether the share button is available in the dashboard screen. |

<DocGinieProvider />

An optional React Context provider if you prefer context over global configuration.

<DocGinieProvider apiUrl="https://api.example.com">
  <AiAnalytics />
</DocGinieProvider>

Individual Views: <Chat />, <Dashboard />, <DashboardViewer />, and External Views

If you need granular control, you can import and render Chat, Dashboard, or DashboardViewer directly.

import { Chat, Dashboard, DashboardViewer, ExternalDashboardAuth, ExternalDashboardViewer } from 'docginie-ai-analytics';

// In your router:
<Route path="/chat" element={<Chat onNavigateDashboard={() => navigate('/dashboard')} />} />
<Route path="/dashboard" element={<Dashboard onBackToChat={() => navigate('/chat')} />} />
<Route path="/dashboard-view" element={<DashboardViewer />} />

// External share views:
<Route
  path="/external/auth"
  element={<ExternalDashboardAuth shareToken="your-token" onSuccess={data => setTokens(data)} />}
/>
<Route
  path="/external/dashboard"
  element={<ExternalDashboardViewer shareToken="your-token" accessToken="your-access-token" />}
/>

<Chat /> and <Dashboard /> Props:

| Prop | Type | Description | | --------------------- | ---------- | ------------------------------------------------------------------------ | | onNavigateDashboard | function | Callback triggered from the Chat view to navigate to the Dashboard. | | onBackToChat | function | Callback triggered from the Dashboard to navigate back to the Chat view. | | isDarkMode | boolean | Current theme state. | | setIsDarkMode | function | Callback to toggle the theme state. |

<DashboardViewer /> - Read-Only Dashboard Component

The DashboardViewer component provides a read-only view of dashboards without editing capabilities. Perfect for embedding dashboards in reports, presentations, or public-facing pages.

Key Differences from <Dashboard />:

| Feature | <Dashboard /> | <DashboardViewer /> | | ------------------- | --------------- | --------------------- | | View Dashboards | ✅ Yes | ✅ Yes | | Drag & Drop Widgets | ✅ Yes | ❌ No | | Delete Widgets | ✅ Yes | ❌ No | | Create Dashboard | ✅ Yes | ❌ No | | Rearrange Widgets | ✅ Yes | ❌ No | | Switch Dashboards | ✅ Yes | ✅ Yes | | Toggle View Mode | ✅ Yes | ✅ Yes | | Dark Mode Support | ✅ Yes | ✅ Yes |

Usage Example:

import { useState } from 'react';
import { DashboardViewer } from 'docginie-ai-analytics';
import 'docginie-ai-analytics/dist/esm/styles.css';

function PublicDashboard() {
  const [isDarkMode, setIsDarkMode] = useState(false);

  return (
    <div style={{ height: '100vh' }}>
      <DashboardViewer
        isDarkMode={isDarkMode}
        setIsDarkMode={setIsDarkMode}
        onBackToChat={() => navigate('/chat')} // Optional
      />
    </div>
  );
}

Props:

| Prop | Type | Required | Description | | --------------- | ---------- | -------- | ----------------------------------------------------------- | | isDarkMode | boolean | No | Current theme state (light/dark mode). | | setIsDarkMode | function | No | Callback to toggle the theme state. | | onBackToChat | function | No | Optional callback to navigate back to chat or another view. |

<ExternalDashboardAuth /> & <ExternalDashboardViewer />

These components facilitate the External Dashboard Sharing functionality, allowing non-users to view a dashboard via a password-protected link generated from within the main ShareDashboardModal.

ExternalDashboardAuth Props: | Prop | Type | Required | Description | | ------------- | ---------- | -------- | -------------------------------------------------------------- | | shareToken | string | Yes | Internal share token from the generated share link URL. | | onSuccess | function | Yes | Callback ({ accessToken, dashboardId }) => void on success. |

ExternalDashboardViewer Props: | Prop | Type | Required | Description | | ------------- | ---------- | -------- | -------------------------------------------------------------- | | shareToken | string | Yes | Internal share token from the generated share link URL. | | accessToken | string | Yes | Access token granted by ExternalDashboardAuth upon unlock. |

Customization & Theming

Dark Mode

DocGinie AI Analytics comes with robust Dark Mode support out of the box. Both <Chat /> and <Dashboard /> handle dark mode gracefully by injecting the dg-dark-mode CSS class.

You can also wrap any standard container with the class to switch CSS variables:

<div class="docginie-ai-analytics dg-dark-mode">
  <AiAnalytics />
</div>

CSS Variables Overrides

The UI is entirely tokenized. You can effortlessly adapt it to your host application's brand by overriding these CSS Custom Properties in your own stylesheet:

/* Your global stylesheet */
.docginie-ai-analytics {
  --dg-text-primary: #111827;
  --dg-text-secondary: #6b7280;
  --dg-btn-primary-bg: #2563eb;
  --dg-btn-primary-hover: #1d4ed8;
  --dg-bg-body: #f3f4f6;
  --dg-accent-color: #e5e7eb;
}

.docginie-ai-analytics.dg-dark-mode {
  --dg-bg-body: #111827;
  --dg-bg-white: #1f2937;
  /* Add more dark mode overrides here */
}

Building from Source

To build the package locally:

cd packages/docginie-ai-analytics
npm install
npm run build

This will run Rollup and output fully typed ECMAScript Modules (ESM) and CommonJS (CJS) bundles, along with compiled .d.ts definitions and minified styles.css into the /dist directory.