@spectrumsense/spectrum-chat-dev/README.md

Embeddable AI Widget - Add trusted, evidence-based answers directly to your website. Simple installation, enterprise-grade security.

# Spectrum Chat

[![npm version](https://img.shields.io/npm/v/@spectrumsense/spectrum-chat.svg)](https://www.npmjs.com/package/@spectrumsense/spectrum-chat)
[![npm downloads](https://img.shields.io/npm/dm/@spectrumsense/spectrum-chat.svg)](https://www.npmjs.com/package/@spectrumsense/spectrum-chat)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Embeddable AI Widget
Add trusted, evidence-based answers directly to your own website—right where families, caregivers, and individuals already turn for guidance. The widget seamlessly integrates with all the data and resources on your site, making them searchable and easy to understand in plain language. Visitors can ask questions in their own words and explore information at their own pace, confident that every answer comes from a source they trust—your organization—while you maintain full control over branding and content.

Simple installation, powerful features, enterprise-grade security.

---

## Quick Start

Add this single line to your website, right before the closing `</body>` tag:

```html
<script src="https://unpkg.com/@spectrumsense/spectrum-chat/dist/spectrum-chat.js" 
        data-site-key="YOUR_SITE_KEY_HERE"></script>
```

**That's it!** The chat widget will appear in the bottom-right corner of your website.

---

## Getting Your Site Key

Contact your Spectrum Chat administrator admin@spectrumsense.ai to obtain your unique site key. It will look like:
```
pub_yourcompany_abc123xyz
```

⚠️ **Important**: Never share your site key publicly or commit it to public repositories.

---

## Features

✨ **One-Line Installation** - Just add the script tag with data attributes  
🎨 **Fully Customizable** - Colors, position, size, branding  
🔒 **Enterprise Security** - JWT tokens, site-key validation, origin checks  
📱 **Mobile Responsive** - Auto-adapts to mobile screens  
💬 **Rich Messaging** - Markdown support, citations, typing indicators  
🌐 **Framework Agnostic** - Works with any website or framework  
⚡ **Lightweight** - ~396KB total, loads asynchronously  
🔧 **Easy Integration** - No build step, no dependencies to install

---
### Method 1: One-Line Installation (Recommended)

```html
<script src="https://unpkg.com/@spectrumsense/spectrum-chat/dist/spectrum-chat.js" 
        data-site-key="pub_yourcompany_abc123xyz"
        data-title="Help Center"
        data-primary-color="#007bff"></script>
```

### Method 2: Configuration Object

```html
<script>
  window.SpectrumChatConfig = {
    siteKey: 'pub_yourcompany_abc123xyz',
    title: 'Help Center',
    primaryColor: '#007bff'
  };
</script>
<script src="https://unpkg.com/@spectrumsense/spectrum-chat/dist/spectrum-chat.js"></script>
```
### Method 3: NPM Installation

```bash
npm install @spectrumsense/spectrum-chat
```

Then include in your HTML:

```html
<script src="node_modules/@spectrumsense/spectrum-chat/dist/spectrum-chat.js" 
        data-site-key="pub_yourcompany_abc123xyz"></script>
```

---

# Complete Configuration Reference

All configuration options can be set using `data-*` attributes on the script tag.

## Required Configuration

| Attribute | Description | Example |
|-----------|-------------|---------|
| `data-site-key` | Your unique site key (required) | `pub_yourcompany_abc123xyz` |

## UI Customization

| Attribute | Description | Default | Example |
|-----------|-------------|---------|---------|
| `data-title` | Widget header title | `AI Assistant` | `Help Center` |
| `data-intro-text` | Welcome message | `Hello! How can I help you today?` | `Welcome! Ask me anything.` |
| `data-primary-color` | Main theme color | `hsl(220 15% 25%)` | `#667eea` |
| `data-user-color` | User message bubble color | `hsl(220 15% 45%)` | `#764ba2` |
| `data-ai-color` | AI message bubble color | `hsl(220 15% 25%)` | `#667eea` |
| `data-fab-icon` | Floating button icon | `💬` | `🤖` |
| `data-fab-color` | Floating button color | `hsl(220 15% 25%)` | `#667eea` |

## Widget Size & Position

| Attribute | Description | Default | Example |
|-----------|-------------|---------|---------|
| `data-width` | Widget width | `320px` | `400px` |
| `data-height` | Widget height | `350px` | `600px` |
| `data-position` | Widget position | `bottom-right` | `bottom-left`, `top-right`, `top-left` |

## Styling

| Attribute | Description | Default | Example |
|-----------|-------------|---------|---------|
| `data-panel-border-radius` | Panel corner radius | `1rem` | `0.5rem`, `8px` |
| `data-panel-shadow` | Panel shadow | `0 8px 32px -8px rgba(0,0,0,0.2)` | `0 4px 12px rgba(0,0,0,0.15)` |

## Features

| Attribute | Description | Default | Example |
|-----------|-------------|---------|---------|
| `data-enable-citations` | Show source citations | `false` | `true` |
| `data-max-messages` | Max messages to store | `100` | `50` |
| `data-debug` | Enable debug logging | `false` | `true` |

---

# Configuration Examples

## Example 1: Basic Setup

```html
<script src="https://unpkg.com/@spectrumsense/spectrum-chat/dist/spectrum-chat.js" 
        data-site-key="pub_yourcompany_abc123xyz"></script>
```

## Example 2: Custom Branding

```html
<script src="https://unpkg.com/@spectrumsense/spectrum-chat/dist/spectrum-chat.js" 
        data-site-key="pub_yourcompany_abc123xyz"
        data-title="Support Chat"
        data-primary-color="#1e3a8a"
        data-user-color="#3b82f6"
        data-ai-color="#1e3a8a"
        data-intro-text="Hi! How can we help you today?"></script>
```

## Example 3: Larger Widget with Citations

```html
<script src="https://unpkg.com/@spectrumsense/spectrum-chat/dist/spectrum-chat.js" 
        data-site-key="pub_yourcompany_abc123xyz"
        data-width="400px"
        data-height="600px"
        data-enable-citations="true"></script>
```

## Example 4: Custom Position

```html
<script src="https://unpkg.com/@spectrumsense/spectrum-chat/dist/spectrum-chat.js" 
        data-site-key="pub_yourcompany_abc123xyz"
        data-position="bottom-left"></script>
```

## Example 5: Full Customization

```html
<script src="https://unpkg.com/@spectrumsense/spectrum-chat/dist/spectrum-chat.js" 
        data-site-key="pub_yourcompany_abc123xyz"
        data-title="Your Assistant"
        data-intro-text="Hello! I'm here to help with any questions."
        data-primary-color="#667eea"
        data-user-color="#764ba2"
        data-ai-color="#667eea"
        data-fab-icon="💬"
        data-width="380px"
        data-height="550px"
        data-position="bottom-right"
        data-enable-citations="true"
        data-panel-border-radius="12px"
        data-debug="false"></script>
```

---

# JavaScript API

Control the widget programmatically:

```javascript
// Open the chat widget
window.SpectrumChatGlobal.open();

// Close the chat widget
window.SpectrumChatGlobal.close();

// Check if widget is open
const isOpen = window.SpectrumChatGlobal.isOpen();

// Get current configuration
const config = window.SpectrumChatGlobal.getConfig();

// Clear session and start fresh
window.SpectrumChatGlobal.clearSession();

// Get conversation ID
const conversationId = window.SpectrumChatGlobal.getConversationId();

// Get session ID (JWT)
const sessionId = window.SpectrumChatGlobal.getSessionId();

// Check if token is valid
const isValid = window.SpectrumChatGlobal.isTokenValid();

// Get token data
const tokenData = window.SpectrumChatGlobal.getTokenData();

// Manually initialize session
await window.SpectrumChatGlobal.initializeSession();

// Reinitialize widget
window.SpectrumChatGlobal.reinitialize();
```
---

## Browser Support

- ✅ Chrome (latest)
- ✅ Firefox (latest)
- ✅ Safari (latest)
- ✅ Edge (latest)
- ✅ Mobile browsers (iOS Safari, Chrome Mobile)

**Minimum Requirements**: ES6 support, Fetch API, Web Components

---

## Framework Integration

### React

```jsx
import { useEffect } from 'react';

function App() {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://unpkg.com/@spectrumsense/spectrum-chat/dist/spectrum-chat.js';
    script.setAttribute('data-site-key', 'pub_yourcompany_abc123xyz');
    script.setAttribute('data-title', 'Help Center');
    script.setAttribute('data-primary-color', '#007bff');
    document.body.appendChild(script);
    
    return () => {
      document.body.removeChild(script);
    };
  }, []);

  return <div>Your App</div>;
}
```

### Vue.js

```vue
<template>
  <div>Your App</div>
</template>

<script setup>
import { onMounted } from 'vue';

onMounted(() => {
  const script = document.createElement('script');
  script.src = 'https://unpkg.com/@spectrumsense/spectrum-chat/dist/spectrum-chat.js';
  script.setAttribute('data-site-key', 'pub_yourcompany_abc123xyz');
  script.setAttribute('data-title', 'Help Center');
  document.body.appendChild(script);
});
</script>
```

### Angular

```typescript
import { Component, OnInit } from '@angular/core';

@Component({
  selector: 'app-root',
  template: '<div>Your App</div>'
})
export class AppComponent implements OnInit {
  ngOnInit() {
    const script = document.createElement('script');
    script.src = 'https://unpkg.com/@spectrumsense/spectrum-chat/dist/spectrum-chat.js';
    script.setAttribute('data-site-key', 'pub_yourcompany_abc123xyz');
    document.body.appendChild(script);
  }
}
```

### WordPress

Add to your theme's `footer.php`:

```php
<script src="https://unpkg.com/@spectrumsense/spectrum-chat/dist/spectrum-chat.js" 
        data-site-key="pub_yourcompany_abc123xyz"
        data-title="Support"></script>
<?php wp_footer(); ?>
</body>
</html>
```

### Static HTML

```html
<!DOCTYPE html>
<html>
<head>
  <title>My Website</title>
</head>
<body>
  <!-- Your content -->
  
  <script src="https://unpkg.com/@spectrumsense/spectrum-chat/dist/spectrum-chat.js" 
          data-site-key="pub_yourcompany_abc123xyz"></script>
</body>
</html>
```

---

## Placement Best Practices

1. **Add before `</body>`** - Load widget last for optimal page performance
2. **Single page apps** - Place in your main template/layout component
3. **Multi-page sites** - Add to your global footer template
4. **Content Management Systems** - Use your CMS's footer widget area

The widget loads asynchronously and won't block page rendering.

---

## Troubleshooting

### Widget Not Appearing?

1. **Check browser console (F12)** for errors
2. **Verify site key** - Ensure it matches your provided key exactly
3. **Check script URL** - Make sure the script loaded successfully
4. **Clear cache** - Try hard refresh (Ctrl+F5 / Cmd+Shift+R)

### Enable Debug Mode

```html
<script src="..." 
        data-site-key="pub_yourcompany_abc123xyz"
        data-debug="true"></script>
```

Open browser console (F12) to see detailed logs including:
- Configuration loading
- Script initialization
- API requests and responses
- Session and token management
- Error details

### Common Issues

**"Origin not allowed" error**
- Your domain is not registered for this site key
- Contact your Spectrum Chat administrator to whitelist your domain

**Widget covered by site content**
- Widget uses `z-index: 999999` - very high priority
- Check if your site has elements with higher z-index
- Inspect element to debug CSS conflicts

---
## Support

Need help?

- 📧 **Email**: admin@spectrumsense.ai
- 🐛 **Issues**: Report bugs or request features
- 💬 **Questions**: Contact your Spectrum Chat administrator

---

## Package Information

**Package Name**: `@spectrumsense/spectrum-chat`  
**Current Version**: `0.2.0`  
**License**: MIT  
**Repository**: GitHub (Private)

---

## License

MIT © Spectrum Sense

---

## About

**Made with ❤️ for neurodivergent and special-needs communities**

Spectrum Chat is an embeddable AI Assistant Widget designed for accessibility and ease of integration. It provides a simple, secure way to add AI-powered chat functionality to any website.

### Key Highlights

- 🎯 **Simple**: One-line installation
- 🔒 **Secure**: Enterprise-grade security built-in
- 🎨 **Customizable**: Match your brand perfectly
- 📱 **Responsive**: Works on all devices
- ⚡ **Fast**: Optimized performance
- 🌐 **Universal**: Works with any website/framework

---

**Last Updated**: October 2025