@justwkendpkg/justwkendai-assistance-widget

v1.1.0

Published

4 months ago

AI-powered chatbot widget for Next.js and React.js — answers site questions, web search fallback, appointment scheduling, navigation, voice support, and tutorials.

0High
0Medium
0Low

justwkend

ai chatbot assistant react nextjs widget voice typescript

AI Assistance (@justwkendpkg/justwkendai-assistance-widget)

An AI-powered chatbot widget for Next.js and React.js projects. Install it as an npm package and add a smart assistant to your site in minutes.

✨ Features

💬 AI-Powered Q&A — Answers questions about your site using LLM context
🗄️ Database Integration — Inject real-time data from your DB (Prisma, SQL, etc.) into the AI context
📊 Table Analysis — Automatically understands and summarizes data from HTML tables on the page
🔍 Web Search Fallback — Searches the web when it can't answer, with source citations
📅 Appointment Scheduling — Inline booking form with validation
🗺️ Site Navigation — Fuzzy search to help users find pages via siteMap
📄 Screen Summary — Describes the current page content
🎤 Voice Controls — Speech-to-text input & text-to-speech output (accessibility)
🎨 Themeable — CSS custom properties, dark mode, glassmorphism
🌍 Multi-language — Responds in the user's language (Italian, English, etc.)

📦 Installation

# npm
npm install @justwkendpkg/justwkendai-assistance-widget

# pnpm
pnpm add @justwkendpkg/justwkendai-assistance-widget

🚀 Quick Start (Next.js App Router)

1. (Server-Side) Create an API Route

Create a file at src/app/api/bot/route.ts (or pages/api/bot.ts).

// app/api/bot/route.ts
import { createBotApiHandler } from '@justwkendpkg/justwkendai-assistance-widget/api';

export const POST = createBotApiHandler({
  siteName: 'My Website',
  ownerName: 'Company Name',
  
  // Optional: Connect your Database
  getExtraContext: async (message) => {
    // If the user asks about products, fetch them from your DB
    if (message.toLowerCase().includes('product')) {
      // const products = await prisma.product.findMany();
      // return JSON.stringify(products);
      return "Available items: Luxury Villa (4 rooms), Beach House (2 rooms).";
    }
    return null;
  },

  aiProvider: async (messages) => {
    // Call OpenAI, Gemini, etc.
    const response = await fetch('https://api.openai.com/v1/chat/completions', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.OPEN_AI_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ model: 'gpt-4o-mini', messages }),
    });
    const data = await response.json();
    return data.choices[0].message.content;
  },
});

2. (Client-Side) Setup the Provider & Widget

Add basic configuration and the floating widget to your layout.

// app/layout.tsx
import { BotProvider, BotWidget } from '@justwkendpkg/justwkendai-assistance-widget';
import '@justwkendpkg/justwkendai-assistance-widget/styles';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <BotProvider
          config={{
            siteName: 'My Website',
            ownerName: 'Company Name',
            apiRoute: '/api/bot', // Point to the route created in step 1
            siteMap: [
              { path: '/', title: 'Home', description: 'Main page' },
              { path: '/villas', title: 'Villas', description: 'Browse our collection of 20+ villas in Puglia' },
            ],
            voiceEnabled: true,
            theme: { primaryColor: '#6366f1' }
          }}
        >
          {children}
          <BotWidget />
        </BotProvider>
      </body>
    </html>
  );
}

⚙️ Configuration (`BotConfig`)

| Property | Type | Description | |---|---|---| | siteName | string | Required. Your site/app name | | ownerName | string | Required. Owner or brand name | | apiRoute | string | Recommended. Server side API route (Next.js /api/bot) | | getExtraContext | (msg) => Promise<string> | Server-side only. Fetch data from DB to help the AI. | | siteMap | SiteMapEntry[] | List of pages for AI to know the site structure | | theme | BotTheme | Colors, fonts, borderRadius, darkMode | | voiceEnabled| boolean | Enable Microphone and TTS |

🗄️ Database Integration

The getExtraContext callback runs on the server. Use it to feed the AI with data that is not visible on the current page:

getExtraContext: async (userMessage) => {
  // Logic to determine what data to fetch
  const results = await db.query("SELECT * FROM houses WHERE rooms > 4");
  return JSON.stringify(results);
}

📄 License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme