floating-copilot-widget 1.4.4 → 1.5.1

package/README.md

@@ -1,6 +1,6 @@
 # Floating Copilot Widget
 
-A lightweight, highly configurable floating chat widget plugin for React websites. Drop it into any React application and get an instantly customizable chat interface that can be dragged, resized, minimized, and maximized.
+A lightweight, highly configurable floating chat widget plugin for React websites with **GitHub Copilot AI integration** for intelligent message processing and API calling.
 
 ## Features
 
@@ -12,6 +12,22 @@ A lightweight, highly configurable floating chat widget plugin for React website
 🎯 **Feature Rich** - Minimize, maximize, close buttons with callbacks
 💬 **Chat Interface** - Built-in message display with auto-scroll
 ⚡ **Performance** - Lightweight with zero external dependencies
+🤖 **AI-Powered** - GitHub Copilot integration for intent analysis
+🔌 **API Integrations** - Easy framework to connect your own APIs
+🎪 **Smart Routing** - Automatically call APIs based on user intent
+📊 **Custom Formatting** - Format API responses beautifully
+
+## What's New in v1.5.0 🎉
+
+- ✅ **GitHub Copilot Integration** - AI-powered intent analysis
+- ✅ **API Integration Framework** - Simple interface to connect your APIs
+- ✅ **Pre-built Integrations** - 7 example API integrations included
+- ✅ **Intent Analysis** - Automatic parameter extraction from user messages
+- ✅ **Auto API Calling** - Routes to correct API based on detected intent
+- ✅ **Interactive Parameter Collection** - Asks for missing fields one by one
+- ✅ **Automatic API Execution** - Triggers API call when all parameters are collected
+- ✅ **Beautiful UI** - Fixed button visibility and improved text contrast (v1.4.4)
+- ✅ **Professional Bot Avatar** - Custom SVG bot icon with gradient
 
 ## Installation
 
@@ -23,6 +39,7 @@ yarn add floating-copilot-widget
 
 ## Quick Start
 
+### Basic Usage
 ```jsx
 import React from 'react';
 import FloatingCopilot from 'floating-copilot-widget';
@@ -30,21 +47,433 @@ import 'floating-copilot-widget/dist/FloatingCopilot.css';
 
 function App() {
   return (
-    <div>
-      <FloatingCopilot
-        config={{
-          title: 'Chat Assistant',
-          position: 'bottom-right',
-          onMessage: (message) => console.log('User said:', message),
-        }}
-      />
-    </div>
+    <FloatingCopilot
+      config={{
+        title: 'Chat Assistant',
+        position: 'bottom-right'
+      }}
+    />
   );
 }
+```
+
+### With Copilot Integration
+```jsx
+import FloatingCopilot, { 
+  createUserAPIIntegration 
+} from 'floating-copilot-widget';
+
+function App() {
+  const apis = [
+    createUserAPIIntegration('https://api.example.com')
+  ];
+
+  return (
+    <FloatingCopilot
+      config={{
+        title: 'AI Assistant',
+        copilot: {
+          config: {
+            githubToken: process.env.REACT_APP_GITHUB_TOKEN
+          },
+          apiIntegrations: apis,
+          enabled: true
+        }
+      }}
+    />
+  );
+}
+```
+
+### With Interactive Parameter Collection
+
+User flow:
+```
+User: "Create a customer"
+Bot: "What is the customer's name?"
+User: "John Doe"
+Bot: "What is the email?"
+User: "john@example.com"
+Bot: "What is the phone?"
+User: "123-456-7890"
+Bot: ✓ "Customer created! ID: 12345"
+```
+
+Implementation:
+```jsx
+import FloatingCopilot, { 
+  createCustomAPIIntegration 
+} from 'floating-copilot-widget';
+
+function App() {
+  const createCustomerAPI = createCustomAPIIntegration({
+    id: 'create_customer',
+    name: 'Create Customer',
+    endpoint: 'https://api.example.com/customers',
+    method: 'POST',
+    intents: ['create_customer', 'add_customer', 'new_customer'],
+    
+    // Define required parameters - system will ask for these one by one
+    requiredParameters: [
+      {
+        name: 'name',
+        description: 'Full name of the customer',
+        type: 'text',
+        required: true,
+        example: 'John Doe'
+      },
+      {
+        name: 'email',
+        description: 'Email address',
+        type: 'email',
+        required: true,
+        example: 'john@example.com'
+      },
+      {
+        name: 'phone',
+        description: 'Phone number',
+        type: 'phone',
+        required: true,
+        example: '(555) 123-4567'
+      }
+    ],
+
+    // Transform parameters into API request
+    buildRequest: (params) => ({
+      name: params.name,
+      email: params.email,
+      phone: params.phone
+    }),
+
+    // Format API response for display
+    formatResponse: (data) => {
+      return `✓ **Customer Created!**\n\n**ID:** ${data.id}\n**Name:** ${data.name}`;
+    }
+  });
+
+  return (
+    <FloatingCopilot
+      config={{
+        title: 'Smart Assistant',
+        copilot: {
+          config: {
+            githubToken: process.env.REACT_APP_GITHUB_TOKEN
+          },
+          apiIntegrations: [createCustomerAPI],
+          enabled: true
+        }
+      }}
+    />
+  );
+}
+```
+
+## Advanced Usage Guide
+
+### Interactive Parameter Collection - Complete Example
+
+This is the most powerful feature. Define what parameters your API needs, and the system automatically asks for them one by one.
+
+**User Interaction Flow:**
+```
+User:  "Create a customer"
+Bot:   "What is the customer's name?"
+User:  "John Doe"
+Bot:   "What is the email?"
+User:  "john@example.com"
+Bot:   "What is the phone?"
+User:  "555-123-4567"
+Bot:   ✓ "Customer created! ID: 12345"
+```
+
+**Implementation:**
+
+Step 1 - Define your API with required parameters:
+```jsx
+import { createCustomAPIIntegration } from 'floating-copilot-widget';
+
+const createCustomerAPI = createCustomAPIIntegration({
+  id: 'create_customer',
+  name: 'Create Customer',
+  endpoint: 'https://api.example.com/customers',
+  method: 'POST',
+  intents: ['create_customer', 'add_customer', 'new_customer'],
+  
+  // Define required parameters - system asks for each missing one
+  requiredParameters: [
+    {
+      name: 'name',
+      description: 'Full name of the customer',
+      type: 'text',
+      required: true,
+      example: 'John Doe'
+    },
+    {
+      name: 'email',
+      description: 'Email address',
+      type: 'email',
+      required: true,
+      example: 'john@example.com'
+    },
+    {
+      name: 'phone',
+      description: 'Phone number',
+      type: 'phone',
+      required: true,
+      example: '(555) 123-4567'
+    },
+    {
+      name: 'address',
+      description: 'Street address',
+      type: 'text',
+      required: false,  // Optional parameters
+      example: '123 Main St'
+    }
+  ],
+  
+  // Transform collected parameters into API request
+  buildRequest: (params) => ({
+    name: params.name,
+    email: params.email,
+    phone: params.phone,
+    address: params.address || ''
+  }),
+  
+  // Format API response for beautiful display
+  formatResponse: (data) => {
+    return `✓ **Customer Created Successfully!**\n\n` +
+      `**ID:** ${data.id}\n` +
+      `**Name:** ${data.name}\n` +
+      `**Email:** ${data.email}`;
+  },
+  
+  // Optional: Control when API should be called
+  shouldCall: (intent, params) => {
+    return !!params.name && !!params.email && !!params.phone;
+  }
+});
+```
 
-export default App;
+Step 2 - Use in FloatingCopilot:
+```jsx
+<FloatingCopilot
+  config={{
+    title: 'Smart Assistant',
+    copilot: {
+      config: {
+        githubToken: process.env.REACT_APP_GITHUB_TOKEN
+      },
+      apiIntegrations: [createCustomerAPI],
+      enabled: true
+    }
+  }}
+/>
 ```
 
+That's it! The system will:
+1. Detect user intent (create_customer)
+2. Ask for missing parameters one by one
+3. Validate each parameter (email format, phone format, etc.)
+4. When all required parameters are collected, automatically call your API
+5. Display the formatted response
+
+### Custom API Integration
+
+Create completely custom APIs:
+
+```jsx
+import type { APIIntegration } from 'floating-copilot-widget';
+
+const customAPI: APIIntegration = {
+  id: 'my_api',
+  name: 'My Custom API',
+  endpoint: 'https://api.example.com/action',
+  method: 'POST',
+  intents: ['my_intent', 'alternative_intent'],
+  
+  requiredParameters: [
+    {
+      name: 'userId',
+      description: 'The user ID',
+      type: 'text',
+      required: true,
+      example: 'user_123'
+    }
+  ],
+  
+  headers: {
+    'Authorization': 'Bearer YOUR_API_KEY'
+  },
+  
+  buildRequest: (params, context) => ({
+    user_id: params.userId,
+    context_data: context?.userData
+  }),
+  
+  formatResponse: (data) => {
+    return `Result: ${JSON.stringify(data, null, 2)}`;
+  },
+  
+  shouldCall: (intent, params) => {
+    return !!params.userId;
+  }
+};
+```
+
+### Parameter Types and Validation
+
+Supported parameter types with automatic validation:
+
+```jsx
+requiredParameters: [
+  {
+    name: 'userEmail',
+    type: 'email',      // ✓ Validates email format
+    description: 'User email address',
+    example: 'user@example.com'
+  },
+  {
+    name: 'phoneNumber',
+    type: 'phone',      // ✓ Validates phone format
+    description: 'User phone',
+    example: '(555) 123-4567'
+  },
+  {
+    name: 'quantity',
+    type: 'number',     // ✓ Validates numeric input
+    description: 'Order quantity',
+    example: '5'
+  },
+  {
+    name: 'startDate',
+    type: 'date',       // ✓ Validates date format
+    description: 'Start date',
+    example: '2026-02-15'
+  },
+  {
+    name: 'notes',
+    type: 'text',       // ✓ Plain text (any value)
+    description: 'Additional notes',
+    example: 'Rush delivery'
+  }
+]
+```
+
+### Pre-built Integrations
+
+Use 7 pre-built templates:
+
+```jsx
+import {
+  createUserAPIIntegration,
+  createSearchAPIIntegration,
+  createAnalysisAPIIntegration,
+  createActionAPIIntegration,
+  createDatabaseAPIIntegration,
+  createWeatherAPIIntegration,
+  createCustomAPIIntegration
+} from 'floating-copilot-widget';
+
+const apis = [
+  createUserAPIIntegration('https://api.example.com'),
+  createSearchAPIIntegration('https://api.example.com'),
+  // ... more
+];
+```
+
+### Direct Copilot Functions
+
+For advanced use cases, call Copilot functions directly:
+
+```jsx
+import {
+  analyzeUserIntent,
+  callAPI,
+  generateParameterPromptOrCallAPI,
+  areAllParametersCollected,
+  validateParameter,
+  getNextMissingParameter
+} from 'floating-copilot-widget';
+
+// Analyze user intent
+const intent = await analyzeUserIntent(
+  { userMessage: 'Create a customer' },
+  config,
+  apis
+);
+
+// Check if all parameters are collected
+const complete = areAllParametersCollected(api, {
+  name: 'John',
+  email: 'john@example.com'
+});
+
+// Validate individual parameter
+const validation = validateParameter('email', userInput, {
+  type: 'email'
+});
+
+// Get next parameter to ask for
+const nextParam = getNextMissingParameter(api, {
+  name: 'John'
+});
+
+// Get prompt or trigger API
+const result = await generateParameterPromptOrCallAPI(
+  api,
+  { name: 'John', email: 'john@example.com', phone: '555-1234' },
+  'create_customer'
+);
+
+if (result.apiResponse) {
+  console.log('API called:', result.apiResponse.data);
+} else {
+  console.log('Ask user:', result.prompt);
+}
+```
+
+### GitHub Token Configuration
+
+The widget automatically looks for your GitHub token in these locations (in order):
+
+1. **Explicit config**: `config.copilot.config.githubToken = 'ghp_...'`
+2. **Environment variables**:
+   - `GITHUB_TOKEN` (Node.js)
+   - `VITE_GITHUB_TOKEN` (Vite)
+   - `REACT_APP_GITHUB_TOKEN` (Create React App)
+3. **Global variable**: `window.__GITHUB_TOKEN__`
+
+**Recommended approach - Use environment variables:**
+
+```bash
+# .env.local
+REACT_APP_GITHUB_TOKEN=ghp_your_token_here
+```
+
+Then no need to pass it in config:
+```jsx
+<FloatingCopilot
+  config={{
+    copilot: {
+      config: {
+        // Token loaded from environment automatically!
+        model: 'gpt-4o'
+      },
+      // ... rest of config
+    }
+  }}
+/>
+```
+
+**To get a token:**
+1. Visit https://github.com/settings/tokens
+2. Click "Generate new token (classic)"
+3. Select scopes:
+   - `copilot` - for Copilot API access
+   - `read:user` - for user data
+4. Copy the token and save securely
+5. Add to `.env.local` file
+
 ## Configuration
 
 Pass a `config` object to customize the widget:
@@ -86,16 +515,29 @@ Pass a `config` object to customize the widget:
     // Layering
     zIndex: 9999,
     
+    // Copilot AI Configuration
+    copilot: {
+      config: {
+        // Token auto-loaded from environment
+        model: 'gpt-4o',           // GPT model to use
+        maxTokens: 2000,           // Max response length
+        temperature: 0.7           // Creativity (0-1)
+      },
+      apiIntegrations: [],         // Your custom APIs
+      enabled: true,               // Enable/disable AI
+      showIntentAnalysis: false    // Show detected intent
+    },
+    
     // Callbacks
-    onMessage: (message) => handleMessage(message),
-    onClose: () => handleClose(),
-    onMinimize: () => handleMinimize(),
-    onMaximize: () => handleMaximize(),
+    onMessage: (message) => console.log(message),
+    onClose: () => {},
+    onMinimize: () => {},
+    onMaximize: () => {},
   }}
 />
 ```
 
-## Configuration Options
+## Configuration
 
 ### Position
 - `bottom-right` (default)
@@ -218,6 +660,14 @@ const config: FloatingCopilotConfig = {
 <FloatingCopilot config={config} />
 ```
 
+## Documentation
+
+- **Quick Start**: Read this README for basic setup
+- **Implementation Guide**: See `QUICK_IMPLEMENTATION_GUIDE.md` for step-by-step parameter collection examples
+- **Full Documentation**: See `COPILOT_INTEGRATION.md` for comprehensive API reference
+- **Setup Reference**: See `COPILOT_SETUP.md` for feature details and best practices
+- **Working Examples**: See `examples/CopilotExample.tsx` for 6 complete working examples
+
 ## License
 
 MIT
@@ -229,3 +679,9 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 ## Support
 
 For issues or questions, please open an issue on the GitHub repository.
+
+**Quick Links:**
+- [GitHub Token Setup](https://github.com/settings/tokens)
+- [Copilot Documentation](https://docs.github.com/en/copilot)
+- [Report Issue](https://github.com/your-org/floating-copilot-widget/issues)
+

package/dist/index.d.ts

@@ -2,3 +2,5 @@ import './FloatingCopilot.css';
 export { FloatingCopilot, default } from './FloatingCopilot';
 export type { FloatingCopilotConfig } from './types';
 export { defaultConfig } from './types';
+export { analyzeUserIntent, callAPI, processUserMessage, generateCopilotResponse, validateAPIIntegration, mergeAPIIntegrations, validateGithubToken, getMissingParameters, getNextMissingParameter, areAllParametersCollected, validateParameter, generateParameterPrompt, generateParameterPromptOrCallAPI, type CopilotConfig, type CopilotIntentRequest, type CopilotIntentResponse, type APIIntegration, type APICallRequest, type APICallResponse, type CopilotChatMessage, type ParameterDefinition } from './services/copilot';
+export { createCustomerAPIIntegration, createUserAPIIntegration, createAnalysisAPIIntegration, createSearchAPIIntegration, createActionAPIIntegration, createDatabaseAPIIntegration, createWeatherAPIIntegration, createCustomAPIIntegration } from './services/integrations';