npm package: @justwkendpkg/justwkendai-assistance-widget
Description: AI-powered chatbot widget for Next.js and React.js — answers site questions, web search fallback, appointment scheduling, navigation, voice support, and tutorials.
Latest version: 1.1.0

# 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

```bash
# 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`).

```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.

```tsx
// 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:

```ts
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