ttp-agent-sdk 2.0.7 → 2.1.1

package/ENHANCED_WIDGET_GUIDE.md

@@ -0,0 +1,330 @@
+# Enhanced AgentWidget - Complete Customization Guide
+
+The `EnhancedAgentWidget` provides extensive customization options while maintaining sensible defaults. Users can customize icons, positioning, colors, animations, and much more.
+
+## Quick Start
+
+```javascript
+import { EnhancedAgentWidget } from 'ttp-agent-sdk';
+
+// Minimal configuration (uses all defaults)
+new EnhancedAgentWidget({
+  agentId: 'your_agent_id',
+  getSessionUrl: async ({ agentId, variables }) => {
+    const response = await fetch('/api/get-session', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ agentId, variables })
+    });
+    const data = await response.json();
+    return data.signedUrl;
+  }
+});
+```
+
+## Complete Configuration Options
+
+### Required Configuration
+
+```javascript
+{
+  agentId: 'your_agent_id',           // Required: Your agent ID
+  getSessionUrl: async ({ agentId, variables }) => { ... }  // Required: Function to get signed URL
+}
+```
+
+### Icon/Image Configuration
+
+```javascript
+{
+  icon: {
+    type: 'microphone',              // 'microphone', 'custom', 'emoji', 'text'
+    customImage: 'https://example.com/icon.png',  // URL for custom image
+    emoji: '🎤',                     // Emoji to display
+    text: 'AI',                      // Text to display
+    size: 'medium'                   // 'small', 'medium', 'large', 'xl'
+  }
+}
+```
+
+**Icon Examples:**
+```javascript
+// Custom image
+icon: { type: 'custom', customImage: 'https://example.com/my-logo.png' }
+
+// Emoji
+icon: { type: 'emoji', emoji: '🤖', size: 'large' }
+
+// Text
+icon: { type: 'text', text: 'HELP', size: 'small' }
+
+// Default microphone
+icon: { type: 'microphone' }
+```
+
+### Positioning Configuration
+
+```javascript
+{
+  position: {
+    vertical: 'bottom',              // 'top', 'bottom', 'center'
+    horizontal: 'right',             // 'left', 'right', 'center'
+    offset: { x: 20, y: 20 }         // Custom offset in pixels
+  }
+}
+```
+
+**Position Examples:**
+```javascript
+// Top-left corner
+position: { vertical: 'top', horizontal: 'left' }
+
+// Center of screen
+position: { vertical: 'center', horizontal: 'center' }
+
+// Custom offset from bottom-right
+position: { 
+  vertical: 'bottom', 
+  horizontal: 'right', 
+  offset: { x: 50, y: 100 } 
+}
+```
+
+### Button Configuration
+
+```javascript
+{
+  button: {
+    size: 'medium',                  // 'small', 'medium', 'large', 'xl'
+    shape: 'circle',                 // 'circle', 'square', 'rounded'
+    primaryColor: '#4F46E5',         // Main button color
+    hoverColor: '#7C3AED',           // Hover state color
+    activeColor: '#EF4444',          // Active/recording color
+    shadow: true,                    // Enable shadow
+    shadowColor: 'rgba(0,0,0,0.15)' // Shadow color
+  }
+}
+```
+
+### Panel Configuration
+
+```javascript
+{
+  panel: {
+    width: 350,                      // Panel width in pixels
+    height: 500,                     // Panel height in pixels
+    borderRadius: 12,                // Border radius in pixels
+    backgroundColor: 'rgba(255,255,255,0.95)',  // Panel background
+    backdropFilter: 'blur(10px)',    // Backdrop filter effect
+    border: '1px solid rgba(0,0,0,0.1)'  // Panel border
+  }
+}
+```
+
+### Header Configuration
+
+```javascript
+{
+  header: {
+    title: 'Voice Assistant',        // Header title
+    showTitle: true,                 // Show/hide title
+    backgroundColor: null,            // null = uses button primaryColor
+    textColor: '#FFFFFF',            // Header text color
+    showCloseButton: true            // Show/hide close button
+  }
+}
+```
+
+### Messages Configuration
+
+```javascript
+{
+  messages: {
+    userBackgroundColor: '#E5E7EB',      // User message background
+    agentBackgroundColor: '#F3F4F6',     // Agent message background
+    systemBackgroundColor: '#DCFCE7',    // System message background
+    errorBackgroundColor: '#FEE2E2',     // Error message background
+    textColor: '#1F2937',                // Text color
+    fontSize: '14px',                    // Font size
+    borderRadius: 8                      // Message border radius
+  }
+}
+```
+
+### Animation Configuration
+
+```javascript
+{
+  animation: {
+    enableHover: true,               // Enable hover animations
+    enablePulse: true,               // Enable pulse animation when recording
+    enableSlide: true,               // Enable slide animations
+    duration: 0.3                    // Animation duration in seconds
+  }
+}
+```
+
+### Behavior Configuration
+
+```javascript
+{
+  behavior: {
+    autoOpen: false,                 // Auto-open panel on load
+    autoConnect: false,              // Auto-connect on load
+    showWelcomeMessage: true,        // Show welcome message
+    welcomeMessage: 'Hello! How can I help you today?'  // Welcome message text
+  }
+}
+```
+
+### Accessibility Configuration
+
+```javascript
+{
+  accessibility: {
+    ariaLabel: 'Voice Assistant',    // ARIA label for button
+    ariaDescription: 'Click to open voice assistant',  // ARIA description
+    keyboardNavigation: true         // Enable keyboard navigation (ESC to close)
+  }
+}
+```
+
+### Custom CSS
+
+```javascript
+{
+  customStyles: `
+    #enhanced-agent-widget {
+      /* Your custom CSS here */
+    }
+  `
+}
+```
+
+## Complete Example
+
+```javascript
+import { EnhancedAgentWidget } from 'ttp-agent-sdk';
+
+const widget = new EnhancedAgentWidget({
+  // Required
+  agentId: 'my_agent_123',
+  getSessionUrl: async ({ agentId, variables }) => {
+    const response = await fetch('/api/get-session', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ agentId, variables })
+    });
+    const data = await response.json();
+    return data.signedUrl;
+  },
+  
+  // Custom icon (company logo)
+  icon: {
+    type: 'custom',
+    customImage: 'https://mycompany.com/logo.png',
+    size: 'large'
+  },
+  
+  // Position in top-left
+  position: {
+    vertical: 'top',
+    horizontal: 'left',
+    offset: { x: 30, y: 30 }
+  },
+  
+  // Brand colors
+  button: {
+    size: 'large',
+    shape: 'rounded',
+    primaryColor: '#FF6B35',
+    hoverColor: '#FF8C42',
+    activeColor: '#FF4444'
+  },
+  
+  // Custom panel styling
+  panel: {
+    width: 400,
+    height: 600,
+    backgroundColor: 'rgba(255, 255, 255, 0.98)',
+    borderRadius: 20,
+    backdropFilter: 'blur(15px)'
+  },
+  
+  // Custom header
+  header: {
+    title: 'My Company Assistant',
+    backgroundColor: '#FF6B35',
+    textColor: '#FFFFFF'
+  },
+  
+  // Custom messages
+  messages: {
+    userBackgroundColor: '#FF6B35',
+    agentBackgroundColor: '#F0F0F0',
+    textColor: '#333333',
+    fontSize: '16px'
+  },
+  
+  // Smooth animations
+  animation: {
+    enableHover: true,
+    enablePulse: true,
+    enableSlide: true,
+    duration: 0.4
+  },
+  
+  // Auto-open for demo
+  behavior: {
+    autoOpen: true,
+    welcomeMessage: 'Welcome to My Company! How can I assist you?'
+  },
+  
+  // Custom variables
+  variables: {
+    company: 'My Company',
+    page: 'homepage',
+    userType: 'visitor'
+  }
+});
+```
+
+## Public API Methods
+
+```javascript
+// Update configuration dynamically
+widget.updateConfig({
+  button: { primaryColor: '#00FF00' },
+  position: { vertical: 'top' }
+});
+
+// Destroy the widget
+widget.destroy();
+```
+
+## Migration from Original AgentWidget
+
+The enhanced widget is fully backward compatible. Simply replace:
+
+```javascript
+// Old
+import { AgentWidget } from 'ttp-agent-sdk';
+new AgentWidget({ ... });
+
+// New
+import { EnhancedAgentWidget } from 'ttp-agent-sdk';
+new EnhancedAgentWidget({ ... });
+```
+
+All existing configurations will work with sensible defaults applied.
+
+## Browser Support
+
+- Chrome 66+
+- Firefox 60+
+- Safari 11.1+
+- Edge 79+
+
+## License
+
+MIT

package/SIGNED_LINK_GUIDE.md

@@ -0,0 +1,218 @@
+# TTP Agent SDK - Signed Link Authentication Guide
+
+## 🔐 Understanding Signed Links
+
+Signed links provide **secure, production-ready authentication** for your voice agents. Your **UI backend** generates secure, time-limited URLs that the widget uses to connect to the **conversation backend**.
+
+## 🏗️ Architecture Overview
+
+```
+User's Frontend → User's Backend → TTP UI Backend → TTP Conversation Backend
+      ↓               ↓               ↓                    ↓
+   Requests        Requests        Generates           Handles
+   signed URL      signed URL      signed URL          conversation
+      ↑               ↑               ↑                    ↑
+   Receives        Receives        Returns             Validates
+   signed URL      signed URL      signed URL          signed token
+```
+
+**The complete flow:**
+1. **User's Frontend** → requests signed URL from **User's Backend**
+2. **User's Backend** → requests signed URL from **TTP UI Backend** (`/api/public/agents`)
+3. **TTP UI Backend** → generates signed URL and returns to **User's Backend**
+4. **User's Backend** → returns signed URL to **User's Frontend**
+5. **User's Frontend** → connects directly to **TTP Conversation Backend** using signed URL
+
+## 🎯 Why Use Signed Links?
+
+### ❌ **Direct Agent ID (Insecure)**
+```javascript
+// DON'T DO THIS IN PRODUCTION
+new EnhancedAgentWidget({
+  agentId: 'agent_12345', // ❌ Visible in network traffic
+  websocketUrl: 'wss://speech.talktopc.com/ws/conv'
+});
+```
+
+**Problems:**
+- Agent ID exposed in browser network tab
+- No cost control
+- No user-specific permissions
+- Security risk
+
+### ✅ **Signed Link (Secure)**
+```javascript
+// PRODUCTION-READY APPROACH
+new EnhancedAgentWidget({
+  agentId: 'agent_12345',
+  getSessionUrl: async ({ agentId, variables }) => {
+    // User's Frontend calls User's Backend
+    const response = await fetch('/api/get-voice-session', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ agentId, variables })
+    });
+    const data = await response.json();
+    return data.signedUrl; // ✅ Secure, time-limited URL from TTP
+  }
+});
+```
+
+**Benefits:**
+- ✅ Secure authentication
+- ✅ Cost control per user
+- ✅ User-specific permissions
+- ✅ Time-limited access
+- ✅ Production-ready
+
+## 🏗️ Implementation Guide
+
+### Step 1: User's Backend Implementation
+
+Your user's backend should have an endpoint that requests signed URLs from TTP:
+
+```javascript
+// User's Backend (Node.js example)
+app.post('/api/get-voice-session', async (req, res) => {
+  try {
+    const { agentId, variables } = req.body;
+    
+    // Validate user authentication
+    const user = await validateUser(req.headers.authorization);
+    if (!user) {
+      return res.status(401).json({ error: 'Unauthorized' });
+    }
+    
+    // Request signed URL from TTP UI Backend
+    const ttpResponse = await fetch('https://backend.talktopc.com/api/public/agents', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${process.env.TTP_API_KEY}` // Your TTP API key
+      },
+      body: JSON.stringify({
+        agentId,
+        variables: {
+          ...variables,
+          userId: user.id,
+          userEmail: user.email
+        }
+      })
+    });
+    
+    if (!ttpResponse.ok) {
+      throw new Error(`TTP API error: ${ttpResponse.status}`);
+    }
+    
+    const ttpData = await ttpResponse.json();
+    
+    // Return signed URL to user's frontend
+    res.json({
+      signedUrl: ttpData.signedUrl
+    });
+    
+  } catch (error) {
+    console.error('Failed to get signed URL from TTP:', error);
+    res.status(500).json({ error: 'Failed to get voice session' });
+  }
+});
+```
+
+### Step 2: User's Frontend Integration
+
+```javascript
+import { EnhancedAgentWidget } from 'ttp-agent-sdk';
+
+new EnhancedAgentWidget({
+  agentId: 'your_agent_id',
+  
+  // User's Frontend calls User's Backend
+  getSessionUrl: async ({ agentId, variables }) => {
+    try {
+      const response = await fetch('/api/get-voice-session', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Authorization': `Bearer ${getAuthToken()}` // User's auth token
+        },
+        body: JSON.stringify({
+          agentId,
+          variables: {
+            ...variables,
+            page: 'homepage',
+            userType: 'customer'
+          }
+        })
+      });
+
+      if (!response.ok) {
+        throw new Error(`Your backend responded with ${response.status}`);
+      }
+
+      const data = await response.json();
+      return data.signedUrl; // This connects directly to TTP Conversation Backend
+      
+    } catch (error) {
+      console.error('Failed to get signed URL from your backend:', error);
+      throw error;
+    }
+  },
+  
+  variables: {
+    page: 'homepage',
+    userType: 'customer',
+    language: 'en'
+  }
+});
+```
+
+## 🔧 Your Current Implementation
+
+Based on your setup, you're already using this pattern:
+
+```javascript
+// Your current LandingPageWidget.jsx
+getSessionUrl: async ({ agentId, variables }) => {
+  const response = await fetch(buildApiUrl('/api/landing/signed-url'), {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      agentId: agentId,
+      variables: variables,
+      page: 'landing',
+      userType: 'visitor'
+    })
+  });
+  
+  const data = await response.json();
+  return data.signedUrl; // This connects to conversation backend
+}
+```
+
+## 🎯 Key Points
+
+1. **UI Backend** (`/api/landing/signed-url`):
+   - Handles authentication
+   - Generates signed URLs
+   - Manages user permissions
+   - Controls costs
+
+2. **Conversation Backend** (`wss://speech.talktopc.com/ws/conv`):
+   - Validates signed tokens
+   - Handles voice conversations
+   - Processes audio streams
+
+3. **Frontend Widget**:
+   - Requests signed URL from UI backend
+   - Connects to conversation backend using signed URL
+   - Never exposes agent IDs directly
+
+## 🚀 Production Benefits
+
+- **Security**: Agent IDs never exposed in frontend
+- **Separation**: UI logic separate from conversation logic
+- **Scalability**: Each backend can scale independently
+- **Control**: UI backend controls access and permissions
+- **Monitoring**: Track usage and costs at UI backend level
+
+This architecture ensures your voice agents are secure, scalable, and production-ready! 🎤✨