admesh-ui-sdk 0.3.1 → 0.4.0

package/CONVERSATIONAL_GUIDE.md

@@ -0,0 +1,326 @@
+# AdMesh Conversational Ad Units Integration Guide
+
+This guide covers how to integrate AdMesh conversational ad units into chat interfaces, AI assistants, and other conversational experiences.
+
+## 🎯 Overview
+
+Conversational ad units are designed to seamlessly inject product recommendations into conversations without disrupting the user experience. They can be displayed inline, as summaries, or as floating overlays.
+
+## 🚀 Quick Integration
+
+### 1. Basic Chat Integration
+
+```tsx
+import React, { useState } from 'react';
+import { AdMeshConversationalUnit } from 'admesh-ui-sdk';
+
+function ChatInterface() {
+  const [messages, setMessages] = useState([]);
+  const [currentRecommendations, setCurrentRecommendations] = useState([]);
+
+  const handleUserMessage = async (userInput) => {
+    // Add user message
+    setMessages(prev => [...prev, { 
+      role: 'user', 
+      content: userInput 
+    }]);
+
+    // Get AI response with recommendations
+    const response = await fetch('/api/chat', {
+      method: 'POST',
+      body: JSON.stringify({ message: userInput })
+    });
+    
+    const data = await response.json();
+    
+    // Add AI response
+    setMessages(prev => [...prev, { 
+      role: 'assistant', 
+      content: data.response,
+      recommendations: data.recommendations 
+    }]);
+  };
+
+  return (
+    <div className="chat-container">
+      {messages.map((message, index) => (
+        <div key={index} className={`message ${message.role}`}>
+          <div className="message-content">
+            {message.content}
+          </div>
+          
+          {/* Show recommendations after assistant messages */}
+          {message.role === 'assistant' && message.recommendations && (
+            <AdMeshConversationalUnit
+              recommendations={message.recommendations}
+              config={{
+                displayMode: 'inline',
+                context: 'chat',
+                maxRecommendations: 3,
+                showPoweredBy: true
+              }}
+              onRecommendationClick={(adId, admeshLink) => {
+                // Track click and open link
+                window.open(admeshLink, '_blank');
+              }}
+            />
+          )}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+### 2. AI Assistant Integration
+
+```tsx
+import { AdMeshConversationalUnit, AdMeshConversationSummary } from 'admesh-ui-sdk';
+
+function AIAssistant() {
+  const [conversation, setConversation] = useState([]);
+  const [sessionSummary, setSessionSummary] = useState(null);
+  const [isSessionEnded, setIsSessionEnded] = useState(false);
+
+  const endConversation = () => {
+    setIsSessionEnded(true);
+    // Generate session summary with recommendations
+    generateSessionSummary();
+  };
+
+  return (
+    <div className="assistant-interface">
+      {/* Conversation messages */}
+      {conversation.map((msg, i) => (
+        <div key={i} className="message">
+          {msg.content}
+          
+          {/* Inline recommendations during conversation */}
+          {msg.recommendations && !isSessionEnded && (
+            <AdMeshConversationalUnit
+              recommendations={msg.recommendations}
+              config={{
+                displayMode: 'minimal',
+                context: 'assistant',
+                maxRecommendations: 1,
+                autoShow: true,
+                delayMs: 1000
+              }}
+            />
+          )}
+        </div>
+      ))}
+
+      {/* Session summary at the end */}
+      {isSessionEnded && sessionSummary && (
+        <AdMeshConversationSummary
+          recommendations={sessionSummary.recommendations}
+          conversationSummary={sessionSummary.text}
+          showTopRecommendations={3}
+          onRecommendationClick={(adId, link) => window.open(link)}
+          onStartNewConversation={() => {
+            setIsSessionEnded(false);
+            setConversation([]);
+            setSessionSummary(null);
+          }}
+        />
+      )}
+    </div>
+  );
+}
+```
+
+## 🎨 Display Modes
+
+### Inline Mode
+Best for: Chat applications, conversational AI
+- Shows full recommendation cards inline with the conversation
+- Doesn't interrupt conversation flow
+- Provides detailed product information
+
+```tsx
+<AdMeshConversationalUnit
+  recommendations={recommendations}
+  config={{
+    displayMode: 'inline',
+    context: 'chat',
+    maxRecommendations: 3
+  }}
+/>
+```
+
+### Minimal Mode
+Best for: Quick suggestions, space-constrained interfaces
+- Shows match count and top recommendation only
+- Very compact footprint
+- Perfect for mobile interfaces
+
+```tsx
+<AdMeshConversationalUnit
+  recommendations={recommendations}
+  config={{
+    displayMode: 'minimal',
+    context: 'assistant',
+    maxRecommendations: 1
+  }}
+/>
+```
+
+### Floating Mode
+Best for: Non-intrusive suggestions, overlay recommendations
+- Appears as floating overlay
+- Dismissible by user
+- Doesn't affect conversation layout
+
+```tsx
+<AdMeshConversationalUnit
+  recommendations={recommendations}
+  config={{
+    displayMode: 'floating',
+    context: 'support',
+    maxRecommendations: 2,
+    position: 'bottom'
+  }}
+  onDismiss={() => console.log('User dismissed recommendations')}
+/>
+```
+
+### Summary Mode
+Best for: End-of-conversation summaries, session wrap-ups
+- Comprehensive summary with top recommendations
+- Action buttons for next steps
+- Perfect for conversation conclusions
+
+```tsx
+<AdMeshConversationalUnit
+  recommendations={recommendations}
+  config={{
+    displayMode: 'summary',
+    context: 'agent'
+  }}
+  conversationSummary="Based on our conversation about CRM solutions..."
+/>
+```
+
+## 🔧 Advanced Configuration
+
+### Delayed Display
+Show recommendations after a delay to avoid overwhelming users:
+
+```tsx
+<AdMeshConversationalUnit
+  recommendations={recommendations}
+  config={{
+    displayMode: 'inline',
+    context: 'chat',
+    autoShow: false,
+    delayMs: 2000  // Show after 2 seconds
+  }}
+/>
+```
+
+### Context-Aware Styling
+Different contexts automatically apply appropriate styling:
+
+```tsx
+// Chat context - casual, friendly styling
+config={{ context: 'chat' }}
+
+// Assistant context - professional, helpful styling  
+config={{ context: 'assistant' }}
+
+// Agent context - business-focused styling
+config={{ context: 'agent' }}
+
+// Support context - problem-solving styling
+config={{ context: 'support' }}
+```
+
+### Custom Theming
+Apply consistent theming across your application:
+
+```tsx
+const theme = {
+  mode: 'dark',
+  accentColor: '#3b82f6',
+  borderRadius: '8px',
+  fontFamily: 'Inter, sans-serif'
+};
+
+<AdMeshConversationalUnit
+  recommendations={recommendations}
+  config={{ displayMode: 'inline', context: 'chat' }}
+  theme={theme}
+/>
+```
+
+## 📱 Mobile Optimization
+
+Conversational ad units are mobile-first and automatically adapt:
+
+```tsx
+// Automatically uses compact layout on mobile
+<AdMeshConversationalUnit
+  recommendations={recommendations}
+  config={{
+    displayMode: 'inline',
+    context: 'chat',
+    maxRecommendations: 2  // Fewer recommendations on mobile
+  }}
+/>
+```
+
+## 🎯 Best Practices
+
+### 1. Timing
+- Show recommendations after the AI provides a helpful response
+- Use delays for non-urgent suggestions
+- Don't show recommendations on every message
+
+### 2. Relevance
+- Only show recommendations when they're contextually relevant
+- Limit to 1-3 recommendations to avoid overwhelming users
+- Prioritize by intent match score
+
+### 3. User Experience
+- Make recommendations dismissible
+- Provide clear value proposition
+- Don't interrupt active conversations
+
+### 4. Performance
+- Load recommendations asynchronously
+- Cache recommendations when possible
+- Use minimal mode for better performance
+
+## 🔗 Integration with AdMesh API
+
+```tsx
+const getRecommendations = async (userQuery, sessionId) => {
+  const response = await fetch('/api/admesh/recommendations', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      query: userQuery,
+      session_id: sessionId,
+      context: 'chat'
+    })
+  });
+  
+  const data = await response.json();
+  return data.recommendations;
+};
+
+// Use in your chat handler
+const handleMessage = async (message) => {
+  const recommendations = await getRecommendations(message, sessionId);
+  
+  if (recommendations && recommendations.length > 0) {
+    // Show conversational ad unit
+    setCurrentRecommendations(recommendations);
+  }
+};
+```
+
+## 🎉 Complete Example
+
+See `examples/conversational-usage.jsx` for a complete working example with all display modes and configurations.

package/README.md

@@ -56,21 +56,34 @@ function App() {
 
 ## 🧩 Components
 
-### AdMeshLayout
+### Core Components
+
+#### AdMeshLayout
 The main layout component that automatically chooses the best display format.
 
-### AdMeshProductCard
+#### AdMeshProductCard
 Individual product recommendation card.
 
-### AdMeshCompareTable
+#### AdMeshCompareTable
 Side-by-side product comparison table.
 
-### AdMeshBadge
+#### AdMeshBadge
 Reusable badge component.
 
-### AdMeshLinkTracker
+#### AdMeshLinkTracker
 Wrapper for tracking any clickable element.
 
+### 💬 Conversational Ad Units
+
+#### AdMeshConversationalUnit
+Smart conversational ad component that adapts to different chat contexts and display modes.
+
+#### AdMeshConversationSummary
+End-of-conversation summary with top recommendations and action buttons.
+
+#### AdMeshInlineRecommendation
+Compact inline recommendation component perfect for chat interfaces.
+
 ## 🎨 Theming
 
 ```tsx
@@ -78,6 +91,186 @@ const theme = {
   mode: 'dark', // 'light' | 'dark'
   accentColor: '#8b5cf6', // Custom accent color
 };
+```
+
+## 💬 Conversational Ad Units
+
+Perfect for chat interfaces, AI assistants, and conversational experiences.
+
+### Quick Start - Conversational Units
+
+```tsx
+import React from 'react';
+import { AdMeshConversationalUnit } from 'admesh-ui-sdk';
+
+const recommendations = [
+  {
+    title: "HubSpot CRM",
+    reason: "Perfect for remote teams with excellent collaboration features",
+    intent_match_score: 0.92,
+    admesh_link: "https://useadmesh.com/track?ad_id=hubspot-123",
+    ad_id: "hubspot-123",
+    product_id: "hubspot-crm",
+    has_free_tier: true,
+    trial_days: 14,
+    keywords: ["CRM", "Sales", "Marketing"]
+  }
+];
+
+function ChatInterface() {
+  return (
+    <div className="chat-container">
+      {/* Your chat messages */}
+      <div className="message">I need a CRM for my team</div>
+
+      {/* AdMesh conversational ad unit */}
+      <AdMeshConversationalUnit
+        recommendations={recommendations}
+        config={{
+          displayMode: 'inline', // 'inline' | 'minimal' | 'floating' | 'summary'
+          context: 'chat',
+          maxRecommendations: 3,
+          showPoweredBy: true
+        }}
+        onRecommendationClick={(adId, admeshLink) => {
+          window.open(admeshLink, '_blank');
+        }}
+      />
+    </div>
+  );
+}
+```
+
+### Display Modes
+
+#### Inline Mode
+Full recommendations displayed inline with the conversation:
+```tsx
+<AdMeshConversationalUnit
+  recommendations={recommendations}
+  config={{ displayMode: 'inline', context: 'chat' }}
+/>
+```
+
+#### Minimal Mode
+Compact display showing match count and top recommendation:
+```tsx
+<AdMeshConversationalUnit
+  recommendations={recommendations}
+  config={{ displayMode: 'minimal', context: 'assistant' }}
+/>
+```
+
+#### Floating Mode
+Floating overlay that doesn't interrupt the conversation flow:
+```tsx
+<AdMeshConversationalUnit
+  recommendations={recommendations}
+  config={{ displayMode: 'floating', context: 'support' }}
+/>
+```
+
+#### Summary Mode
+End-of-conversation summary with top recommendations:
+```tsx
+<AdMeshConversationalUnit
+  recommendations={recommendations}
+  config={{ displayMode: 'summary', context: 'agent' }}
+  conversationSummary="We discussed your CRM needs..."
+/>
+```
+
+### Individual Conversational Components
+
+#### AdMeshConversationSummary
+Perfect for end-of-conversation summaries:
+
+```tsx
+import { AdMeshConversationSummary } from 'admesh-ui-sdk';
+
+<AdMeshConversationSummary
+  recommendations={recommendations}
+  conversationSummary="Here's what we discussed and found for you..."
+  showTopRecommendations={3}
+  onRecommendationClick={(adId, link) => window.open(link)}
+  onStartNewConversation={() => startNewChat()}
+/>
+```
+
+#### AdMeshInlineRecommendation
+Compact inline recommendations for chat bubbles:
+
+```tsx
+import { AdMeshInlineRecommendation } from 'admesh-ui-sdk';
+
+<AdMeshInlineRecommendation
+  recommendation={recommendation}
+  compact={true}
+  showReason={true}
+  onClick={(adId, link) => window.open(link)}
+/>
+```
+
+### Configuration Options
+
+#### ConversationalAdConfig
+
+```tsx
+interface ConversationalAdConfig {
+  displayMode: 'inline' | 'summary' | 'floating' | 'minimal';
+  context: 'chat' | 'assistant' | 'agent' | 'support';
+  maxRecommendations?: number;     // Default: 3
+  showPoweredBy?: boolean;         // Default: true
+  autoShow?: boolean;              // Default: true
+  delayMs?: number;                // Default: 0
+  position?: 'top' | 'bottom' | 'inline'; // Default: 'inline'
+}
+```
+
+### Integration Examples
+
+#### Chat Application
+```tsx
+function ChatApp() {
+  const [messages, setMessages] = useState([]);
+  const [recommendations, setRecommendations] = useState([]);
+
+  const handleUserMessage = async (message) => {
+    // Add user message
+    setMessages(prev => [...prev, { role: 'user', content: message }]);
+
+    // Get AI response and recommendations
+    const response = await getAIResponse(message);
+    setMessages(prev => [...prev, { role: 'assistant', content: response.text }]);
+
+    // Show recommendations if available
+    if (response.recommendations) {
+      setRecommendations(response.recommendations);
+    }
+  };
+
+  return (
+    <div className="chat-container">
+      {messages.map((msg, i) => (
+        <div key={i} className={`message ${msg.role}`}>
+          {msg.content}
+
+          {/* Show recommendations after assistant messages */}
+          {msg.role === 'assistant' && recommendations.length > 0 && (
+            <AdMeshConversationalUnit
+              recommendations={recommendations}
+              config={{
+                displayMode: 'inline',
+                context: 'chat',
+                maxRecommendations: 2
+              }}
+            />
+          )}
+        </div>
+      ))}
+    </div>
+  );
+}
 
 <AdMeshLayout theme={theme} recommendations={recommendations} />
 ```

package/dist/index.d.ts

@@ -28,6 +28,43 @@ export declare interface AdMeshConfig {
     debug?: boolean;
 }
 
+export declare const AdMeshConversationalUnit: default_2.FC<AdMeshConversationalUnitProps>;
+
+export declare interface AdMeshConversationalUnitProps {
+    recommendations: AdMeshRecommendation[];
+    config: ConversationalAdConfig;
+    theme?: AdMeshTheme;
+    conversationSummary?: string;
+    userQuery?: string;
+    sessionId?: string;
+    onRecommendationClick?: (adId: string, admeshLink: string) => void;
+    onDismiss?: () => void;
+    className?: string;
+}
+
+export declare const AdMeshConversationSummary: default_2.FC<AdMeshConversationSummaryProps>;
+
+export declare interface AdMeshConversationSummaryProps {
+    recommendations: AdMeshRecommendation[];
+    conversationSummary: string;
+    theme?: AdMeshTheme;
+    showTopRecommendations?: number;
+    onRecommendationClick?: (adId: string, admeshLink: string) => void;
+    onStartNewConversation?: () => void;
+    className?: string;
+}
+
+export declare const AdMeshInlineRecommendation: default_2.FC<AdMeshInlineRecommendationProps>;
+
+export declare interface AdMeshInlineRecommendationProps {
+    recommendation: AdMeshRecommendation;
+    theme?: AdMeshTheme;
+    compact?: boolean;
+    showReason?: boolean;
+    onClick?: (adId: string, admeshLink: string) => void;
+    className?: string;
+}
+
 export declare const AdMeshLayout: default_2.FC<AdMeshLayoutProps>;
 
 export declare interface AdMeshLayoutProps {
@@ -141,6 +178,20 @@ export declare type BadgeVariant = 'primary' | 'secondary' | 'success' | 'warnin
 
 export declare const buildAdMeshLink: (baseLink: string, adId: string, additionalParams?: Record<string, string>) => string;
 
+export declare interface ConversationalAdConfig {
+    displayMode: ConversationalDisplayMode;
+    context: ConversationContext;
+    maxRecommendations?: number;
+    showPoweredBy?: boolean;
+    autoShow?: boolean;
+    delayMs?: number;
+    position?: 'top' | 'bottom' | 'inline';
+}
+
+export declare type ConversationalDisplayMode = 'inline' | 'summary' | 'floating' | 'minimal';
+
+export declare type ConversationContext = 'chat' | 'assistant' | 'agent' | 'support';
+
 export declare const DEFAULT_CONFIG: {
     trackingEnabled: boolean;
     debug: boolean;