🌿 GreenZone Agent

Enterprise-grade AI Chat Widget powered by OpenAI

Developed by Trí Nguyễn — CTO, The GreenZone

Features • Installation • Usage • Configuration • API

✨ Features

| Feature | Description | |---------|-------------| | 🚀 Streaming Responses | Real-time AI responses with OpenAI streaming | | 🔐 Authentication | Auto-sends JWT token from localStorage | | 📎 File Attachments | Upload PDFs and documents for AI analysis | | 💾 Chat History | Persistent conversation history with session management | | 🎨 Themeable | Fully customizable colors, fonts, and branding | | ⚡ Virtualized List | Optimized performance with thousands of messages | | 📱 Responsive | Works on desktop and mobile with fullscreen mode | | 🔧 Resizable Panel | Drag to resize chat panel width | | 🌐 Web Search | Built-in web search tool integration |

📦 Installation

# npm
npm install @dev.tringuyen/greenzone-agent

# yarn
yarn add @dev.tringuyen/greenzone-agent

# pnpm
pnpm add @dev.tringuyen/greenzone-agent

🚀 Usage

Quick Start

import { ChatWidget } from '@dev.tringuyen/greenzone-agent';

function App() {
  return (
    <>
      <YourApp />
      
      {/* Drop-in AI Chat - Just one line! */}
      <ChatWidget apiBaseUrl="https://your-api.com" />
    </>
  );
}

With Full Configuration

import { ChatWidget } from '@dev.tringuyen/greenzone-agent';

function App() {
  return (
    <ChatWidget 
      apiBaseUrl="https://api.your-domain.com"
      projectId="my-project-123"
      position="bottom-right"
      panelWidth={500}
      theme={{
        primaryColor: '#14B8A6',
        fontFamily: 'Inter, sans-serif',
      }}
      branding={{
        title: 'My AI Assistant',
        subtitle: 'Powered by AI',
        welcomeMessage: 'How can I help you today?',
        inputPlaceholder: 'Type your message...',
        logo: 'https://example.com/logo.png',
      }}
      features={{
        fileUpload: true,
        history: true,
        resize: true,
        fullscreen: true,
      }}
      context={{
        currentPage: 'dashboard',
        systemPrompt: 'You are a helpful assistant.',
      }}
      onOpen={() => console.log('Chat opened')}
      onClose={() => console.log('Chat closed')}
    />
  );
}

⚙️ Configuration

ChatWidgetConfig

| Property | Type | Default | Description | |----------|------|---------|-------------| | apiBaseUrl | string | required | Base URL of your API (origin only, e.g., https://api.example.com) | | projectId | string | undefined | Project ID sent as X-Project-Id header | | isOpen | boolean | undefined | Controlled open state (optional) | | onOpenChange | (isOpen: boolean) => void | undefined | Callback when open state changes | | position | 'bottom-right' \| 'bottom-left' | 'bottom-right' | Trigger button position | | panelWidth | number | 500 | Initial panel width in pixels | | zIndex | number | 9999 | Z-index of the widget |

Theme Options

theme?: {
  primaryColor?: string;      // Default: '#14B8A6'
  backgroundColor?: string;   // Default: '#FFFFFF'
  textColor?: string;         // Default: '#0F172A'
  fontFamily?: string;        // Default: 'system-ui'
}

Branding

branding?: {
  title?: string;             // Default: 'GreenZone AI'
  subtitle?: string;          // Subtitle under title
  welcomeMessage?: string;    // Welcome screen message
  inputPlaceholder?: string;  // Input field placeholder
  logo?: string;              // Logo URL (optional)
}

Feature Flags

features?: {
  fileUpload?: boolean;   // Enable PDF upload (default: true)
  history?: boolean;      // Enable chat history (default: true)
  resize?: boolean;       // Enable panel resizing (default: true)
  fullscreen?: boolean;   // Enable fullscreen mode (default: true)
}

🔐 Authentication

The widget automatically sends authentication headers with every API request:

Authorization: Bearer <token>
X-Project-Id: <projectId>

To authenticate, store the JWT token in localStorage:

// After user login
localStorage.setItem('auth_token', 'your-jwt-token');

The widget will automatically include this token in all requests.

🔌 API Requirements

Your backend needs to implement these endpoints:

| Method | Endpoint | Description | |--------|----------|-------------| | POST | /api/v1/chat | Streaming chat (SSE) | | POST | /api/v1/files/upload | File upload | | GET | /api/v1/files/status/:jobId | Upload status polling | | GET | /api/history | List chat sessions | | POST | /api/history | Save chat session | | DELETE | /api/history/:id | Delete session |

Note: Chat & file endpoints use /api/v1/, while history uses /api/ (no v1).

📋 Requirements

• React 18.0+
• Tailwind CSS (components use Tailwind utility classes)
• Motion 11.0+ (framer-motion successor)

Tailwind CSS Setup

Add this to your CSS to include widget styles:

@import "tailwindcss";
@source "../node_modules/@dev.tringuyen/greenzone-agent/dist/**/*.js";

🛠️ Development

# Clone the repo
git clone https://github.com/thegreenzone/greenzone-agent.git

# Install dependencies
yarn install

# Build
yarn build

# Watch mode
yarn dev

📄 License

UNLICENSED - Proprietary software. All rights reserved.

Built with ❤️ by The GreenZone

Making AI accessible for everyone