@mordn/chat-widget 0.1.3 → 0.1.4

package/README.md

@@ -2,66 +2,210 @@
 
 A customizable AI chat widget for React/Next.js applications with built-in conversation persistence.
 
-## Installation
+## Quick Start
 
 ```bash
-npm install @mordn/chat-widget
+# 1. Install the package
+npm install @mordn/chat-widget drizzle-kit
+
+# 2. Run the setup wizard
+npx @mordn/chat-widget
 ```
 
+The setup wizard creates all required files:
+- API routes (`/api/chat/...`)
+- `drizzle.config.ts`
+- `.env.example`
+
 ## Requirements
 
 - Next.js 14+ (App Router)
 - React 18+
 - PostgreSQL database (Supabase recommended)
 - Tailwind CSS v4
-- Vercel AI SDK
 
 ## Setup
 
 ### 1. Environment Variables
 
-Add your database connection string and AI Gateway API key:
+Copy `.env.example` to `.env.local` and fill in your credentials:
 
 ```env
+# Database (Required)
 DATABASE_URL="postgresql://postgres.xxx:[PASSWORD]@aws-0-region.pooler.supabase.com:6543/postgres"
+
+# AI Provider (Required)
 AI_GATEWAY_API_KEY="your-ai-gateway-key"
 ```
 
 ### 2. Database Setup
 
-Install drizzle-kit as a dev dependency:
+Push the schema to your database:
 
 ```bash
-npm install drizzle-kit --save-dev
+npx drizzle-kit push
 ```
 
-Create `drizzle.config.ts` in your project root:
+### 3. Configure Your AI Model
+
+Open `app/api/chat/route.ts` and update the config:
 
 ```typescript
-import 'dotenv/config';
-import { defineConfig } from 'drizzle-kit';
-
-export default defineConfig({
-  schema: './node_modules/@mordn/chat-widget/dist/schema/index.js',
-  out: './drizzle',
-  dialect: 'postgresql',
-  dbCredentials: {
-    url: process.env.DATABASE_URL!,
-  },
-});
+const DEVELOPER_CONFIG = {
+  model: 'openai/gpt-4o', // Your AI model
+  systemPrompt: 'You are a helpful assistant',
+  temperature: 0.7,
+};
 ```
 
-Run the migration to create tables:
+### 4. Add the Widget
 
-```bash
-npx drizzle-kit push
+```tsx
+'use client';
+
+import { ChatWidget } from '@mordn/chat-widget';
+import '@mordn/chat-widget/styles.css';
+
+export default function Page() {
+  return (
+    <ChatWidget
+      // Required
+      userId="user-123"
+
+      // Theme: 'light' | 'dark'
+      theme={{ mode: 'light' }}
+
+      // Feature toggles
+      features={{
+        fileUpload: false,  // Requires Supabase Storage setup
+      }}
+
+      // Display options
+      display={{
+        defaultOpen: false,      // Start with chat open
+        size: 'default',         // 'compact' | 'default' | 'large' | 'full'
+        resizable: true,         // Allow resizing
+        showToggleButton: true,  // Show FAB toggle button
+      }}
+
+      // Starter prompts shown on empty chat
+      starterPrompts={[
+        { title: "What can you help me with?" },
+        { title: "How do I get started?" },
+      ]}
+    />
+  );
+}
+```
+
+---
+
+## File Uploads (Optional)
+
+To enable image attachments, you need Supabase Storage and to enable the feature:
+
+```tsx
+<ChatWidget
+  userId="user-123"
+  features={{ fileUpload: true }}
+/>
+```
+
+### 1. Create Storage Bucket
+
+1. Go to your [Supabase Dashboard](https://supabase.com/dashboard)
+2. Navigate to **Storage** → **New Bucket**
+3. Create a bucket named `chat-attachments`
+4. Set it to **Public** (or configure RLS policies for private access)
+
+### 2. Add Environment Variables
+
+```env
+NEXT_PUBLIC_SUPABASE_URL="https://your-project.supabase.co"
+SUPABASE_SERVICE_ROLE_KEY="your-service-role-key"
+```
+
+You can find these in Supabase Dashboard → **Settings** → **API**
+
+### 3. Create Upload Route
+
+When running `npx @mordn/chat-widget`, select **Yes** when asked about the upload route.
+
+---
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `userId` | `string` | **required** | User identifier for storing conversations |
+| `conversationId` | `string` | - | Load a specific conversation |
+| `initialMessages` | `array` | - | Pre-fill the chat with messages |
+| `className` | `string` | - | Additional CSS classes |
+| `theme` | `ThemeConfig` | - | Theme configuration |
+| `features` | `FeatureConfig` | - | Feature toggles |
+| `display` | `DisplayConfig` | - | Display options |
+
+### ThemeConfig
+
+```typescript
+{
+  mode?: 'light' | 'dark';
+}
 ```
 
-### 3. API Routes
+### FeatureConfig
 
-Create the following API routes in your Next.js app:
+```typescript
+{
+  fileUpload?: boolean;  // Enable file attachments (default: false)
+  webSearch?: boolean;   // Enable web search toggle
+}
+```
 
-#### `app/api/chat/route.ts` - Main Chat Endpoint
+### DisplayConfig
+
+```typescript
+{
+  width?: string;              // e.g., '400px' or '30vw'
+  defaultOpen?: boolean;       // Start with chat open (default: false)
+  showToggleButton?: boolean;  // Show FAB toggle button (default: true)
+  toggleButtonPosition?: {
+    bottom?: string;
+    right?: string;
+  };
+}
+```
+
+---
+
+## Exports
+
+```typescript
+// Main component
+import { ChatWidget } from '@mordn/chat-widget';
+import '@mordn/chat-widget/styles.css';
+
+// Database utilities (server-side only)
+import {
+  db,
+  conversations,
+  messages,
+  createChat,
+  loadChat,
+  saveChat,
+  getConversations,
+  deleteConversation,
+  updateConversationTitle,
+  eq, and, or, desc, asc, sql
+} from '@mordn/chat-widget/api';
+```
+
+---
+
+## Generated Files Reference
+
+<details>
+<summary><strong>app/api/chat/route.ts</strong> - Main Chat Endpoint</summary>
 
 ```typescript
 import { saveChat, updateConversationTitle, db, conversations, messages, eq } from '@mordn/chat-widget/api';
@@ -69,123 +213,128 @@ import { convertToModelMessages, streamText, UIMessage } from 'ai';
 
 export const maxDuration = 30;
 
-// DEVELOPER CONFIG - Set these for your app
 const DEVELOPER_CONFIG = {
-  model: 'openai/gpt-4o', // Your AI model (provider/model format)
+  model: 'openai/gpt-4o',
   systemPrompt: 'You are a helpful assistant',
   temperature: 0.7,
 };
 
 export async function POST(req: Request) {
-  const body = await req.json();
-  const userId = req.headers.get('X-User-Id');
-
-  if (!userId) {
-    return new Response('userId is required in X-User-Id header', { status: 400 });
-  }
-
-  const chatMessages: UIMessage[] = body.messages || [];
-  const id: string = body.id || 'temp-id';
-
-  const { model, systemPrompt, temperature } = DEVELOPER_CONFIG;
-
-  // Check if conversation exists, create if not
-  const existingConv = await db
-    .select({ id: conversations.id })
-    .from(conversations)
-    .where(eq(conversations.id, id))
-    .limit(1);
+  try {
+    const body = await req.json();
+    const userId = req.headers.get('X-User-Id');
 
-  if (!existingConv.length) {
-    await db.insert(conversations).values({
-      id,
-      userId,
-      title: 'New Chat',
-      metadata: {},
-    });
-  }
+    if (!userId) {
+      return new Response('userId is required in X-User-Id header', { status: 400 });
+    }
 
-  // Save the new user message
-  const userMessages = chatMessages.filter(msg => msg.role === 'user');
-  if (userMessages.length > 0) {
-    const newUserMessage = userMessages[userMessages.length - 1];
-    const textPart = newUserMessage.parts?.find(p => p.type === 'text') as { text: string } | undefined;
-    const fileParts = newUserMessage.parts?.filter(p => p.type === 'file') || [];
+    const chatMessages: UIMessage[] = body.messages || [];
+    const id: string = body.id || 'temp-id';
+    const { model, systemPrompt, temperature } = DEVELOPER_CONFIG;
 
-    const existingMsg = await db
-      .select({ id: messages.id })
-      .from(messages)
-      .where(eq(messages.id, newUserMessage.id))
+    const existingConv = await db
+      .select({ id: conversations.id })
+      .from(conversations)
+      .where(eq(conversations.id, id))
       .limit(1);
 
-    if (!existingMsg.length) {
-      await db.insert(messages).values({
-        id: newUserMessage.id,
-        conversationId: id,
-        role: newUserMessage.role,
-        content: textPart?.text || '',
-        files: fileParts,
-        model: model,
-        metadata: { parts: newUserMessage.parts || [] },
+    if (!existingConv.length) {
+      await db.insert(conversations).values({
+        id,
+        userId,
+        title: 'New Chat',
+        metadata: {},
       });
     }
 
-    // Update conversation title if needed
-    if (textPart?.text) {
-      const conv = await db
-        .select({ title: conversations.title })
-        .from(conversations)
-        .where(eq(conversations.id, id))
+    const userMessages = chatMessages.filter(msg => msg.role === 'user');
+    if (userMessages.length > 0) {
+      const newUserMessage = userMessages[userMessages.length - 1];
+      const textPart = newUserMessage.parts?.find(p => p.type === 'text') as { text: string } | undefined;
+      const fileParts = newUserMessage.parts?.filter(p => p.type === 'file') || [];
+
+      const existingMsg = await db
+        .select({ id: messages.id })
+        .from(messages)
+        .where(eq(messages.id, newUserMessage.id))
         .limit(1);
 
-      if (conv[0]?.title === 'New Chat') {
-        await updateConversationTitle(id, textPart.text.slice(0, 100));
+      if (!existingMsg.length) {
+        await db.insert(messages).values({
+          id: newUserMessage.id,
+          conversationId: id,
+          role: newUserMessage.role,
+          content: textPart?.text || '',
+          files: fileParts,
+          model: model,
+          metadata: { parts: newUserMessage.parts || [] },
+        });
       }
-    }
-  }
 
-  // Transform messages for AI (handle images)
-  const transformedMessages = chatMessages.map(msg => {
-    if (msg.role === 'user' && msg.parts) {
-      const textPart = msg.parts.find(p => p.type === 'text');
-      const fileParts = msg.parts.filter(p => p.type === 'file');
+      if (textPart?.text) {
+        const conv = await db
+          .select({ title: conversations.title })
+          .from(conversations)
+          .where(eq(conversations.id, id))
+          .limit(1);
 
-      if (fileParts.length > 0) {
-        const content = [];
-        if (textPart && 'text' in textPart) {
-          content.push({ type: 'text', text: textPart.text });
-        }
-        for (const file of fileParts) {
-          if ('mediaType' in file && file.mediaType?.startsWith('image/')) {
-            content.push({ type: 'image', image: (file as any).url });
-          }
+        if (conv[0]?.title === 'New Chat') {
+          await updateConversationTitle(id, textPart.text.slice(0, 100));
         }
-        return { ...msg, content };
       }
     }
-    return msg;
-  });
-
-  const result = streamText({
-    model: model,
-    messages: convertToModelMessages(transformedMessages),
-    system: systemPrompt,
-    temperature: temperature,
-  });
-
-  return result.toUIMessageStreamResponse({
-    sendSources: true,
-    sendReasoning: true,
-    onFinish: ({ messages: finalMessages }) => {
-      if (finalMessages.length > 0) {
-        saveChat({ chatId: id, messages: finalMessages, model, userId });
+
+    const transformedMessages = chatMessages.map(msg => {
+      if (msg.role === 'user' && msg.parts) {
+        const textPart = msg.parts.find(p => p.type === 'text');
+        const fileParts = msg.parts.filter(p => p.type === 'file');
+
+        if (fileParts.length > 0) {
+          const content: any[] = [];
+          if (textPart && 'text' in textPart) {
+            content.push({ type: 'text', text: textPart.text });
+          }
+          for (const file of fileParts) {
+            if ('mediaType' in file && (file as any).mediaType?.startsWith('image/')) {
+              content.push({ type: 'image', image: (file as any).url });
+            }
+          }
+          return { ...msg, content };
+        }
       }
-    },
-  });
+      return msg;
+    });
+
+    const result = streamText({
+      model: model,
+      messages: convertToModelMessages(transformedMessages),
+      system: systemPrompt,
+      temperature: temperature,
+    });
+
+    return result.toUIMessageStreamResponse({
+      sendSources: true,
+      sendReasoning: true,
+      onFinish: ({ messages: finalMessages }) => {
+        if (finalMessages.length > 0) {
+          saveChat({ chatId: id, messages: finalMessages, model, userId });
+        }
+      },
+    });
+  } catch (error) {
+    console.error('Chat API error:', error);
+    return new Response(JSON.stringify({ error: 'Internal server error' }), {
+      status: 500,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
 }
 ```
 
-#### `app/api/chat/history/route.ts` - List Conversations
+</details>
+
+<details>
+<summary><strong>app/api/chat/history/route.ts</strong> - List Conversations</summary>
 
 ```typescript
 import { NextResponse } from 'next/server';
@@ -219,7 +368,10 @@ export async function GET(request: Request) {
 }
 ```
 
-#### `app/api/chat/history/[conversationId]/route.ts` - Get Conversation Messages
+</details>
+
+<details>
+<summary><strong>app/api/chat/history/[conversationId]/route.ts</strong> - Get Conversation</summary>
 
 ```typescript
 import { NextResponse } from 'next/server';
@@ -238,7 +390,6 @@ export async function GET(
       return NextResponse.json({ error: 'userId is required' }, { status: 400 });
     }
 
-    // Verify the conversation belongs to the user
     const conv = await db
       .select({
         id: conversations.id,
@@ -295,17 +446,28 @@ export async function GET(
 }
 ```
 
-#### `app/api/chat/upload/route.ts` - File Upload (Optional)
+</details>
+
+<details>
+<summary><strong>app/api/chat/upload/route.ts</strong> - File Upload (Optional)</summary>
 
 ```typescript
 import { createClient } from '@supabase/supabase-js';
 import { nanoid } from 'nanoid';
 
-const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL!;
-const supabaseServiceKey = process.env.SUPABASE_SERVICE_ROLE_KEY!;
-
 export async function POST(req: Request) {
   try {
+    const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL;
+    const supabaseServiceKey = process.env.SUPABASE_SERVICE_ROLE_KEY;
+
+    // Check for required environment variables
+    if (!supabaseUrl || !supabaseServiceKey) {
+      console.error('Missing Supabase environment variables');
+      return Response.json({
+        error: 'File upload is not configured. Please set up Supabase Storage environment variables.'
+      }, { status: 503 });
+    }
+
     const formData = await req.formData();
     const file = formData.get('file') as File;
     const conversationId = formData.get('conversationId') as string;
@@ -319,12 +481,10 @@ export async function POST(req: Request) {
       return Response.json({ error: 'userId is required' }, { status: 400 });
     }
 
-    // Only images supported
     if (!file.type.startsWith('image/')) {
       return Response.json({ error: 'Only image files are supported' }, { status: 400 });
     }
 
-    // 5MB limit
     if (file.size > 5 * 1024 * 1024) {
       return Response.json({ error: 'File size exceeds 5MB limit' }, { status: 400 });
     }
@@ -366,129 +526,9 @@ export async function POST(req: Request) {
 }
 ```
 
-### 4. Use the Widget
-
-**For sitewide usage**, create a provider component:
-
-```tsx
-// components/chat-provider.tsx
-'use client';
+</details>
 
-import { ChatWidget } from '@mordn/chat-widget';
-import '@mordn/chat-widget/styles.css';
-import { useAuth } from '@/contexts/auth-context'; // Your auth hook
-
-export function ChatProvider() {
-  const { user, loading } = useAuth();
-
-  if (loading || !user) {
-    return null;
-  }
-
-  return (
-    <ChatWidget
-      userId={user.id}
-      theme={{ mode: 'dark' }}
-    />
-  );
-}
-```
-
-Add to your root layout:
-
-```tsx
-// app/layout.tsx
-import { ChatProvider } from '@/components/chat-provider';
-
-export default function RootLayout({ children }) {
-  return (
-    <html>
-      <body>
-        {children}
-        <ChatProvider />
-      </body>
-    </html>
-  );
-}
-```
-
-## Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `userId` | `string` | **required** | User identifier for storing conversations |
-| `conversationId` | `string` | - | Load a specific conversation |
-| `initialMessages` | `array` | - | Pre-fill the chat with messages |
-| `className` | `string` | - | Additional CSS classes |
-| `theme` | `ThemeConfig` | - | Theme configuration |
-| `features` | `FeatureConfig` | - | Feature toggles |
-| `display` | `DisplayConfig` | - | Display options |
-
-### ThemeConfig
-
-```typescript
-{
-  mode?: 'light' | 'dark';
-  primaryColor?: string;
-  backgroundColor?: string;
-  textColor?: string;
-}
-```
-
-### FeatureConfig
-
-```typescript
-{
-  fileUpload?: boolean;  // Enable file attachments (default: true)
-  webSearch?: boolean;   // Enable web search toggle
-}
-```
-
-### DisplayConfig
-
-```typescript
-{
-  width?: string;              // e.g., '400px' or '30vw' (default: '30vw')
-  defaultOpen?: boolean;       // Start with chat open (default: false)
-  showToggleButton?: boolean;  // Show FAB toggle button (default: true)
-  toggleButtonPosition?: {
-    bottom?: string;
-    right?: string;
-  };
-}
-```
-
-## Exports
-
-```typescript
-// Main component
-import { ChatWidget } from '@mordn/chat-widget';
-import '@mordn/chat-widget/styles.css';
-
-// Database utilities (server-side only)
-import {
-  db,
-  conversations,
-  messages,
-  createChat,
-  loadChat,
-  saveChat,
-  getConversations,
-  deleteConversation,
-  updateConversationTitle,
-  eq, and, or, desc, asc, sql
-} from '@mordn/chat-widget/api';
-
-// Types
-import type {
-  ChatWidgetConfig,
-  ThemeConfig,
-  FeatureConfig,
-  DisplayConfig,
-  Conversation,
-  Message
-} from '@mordn/chat-widget';
-```
+---
 
 ## License