@spectrumsense/spectrum-chat-dev/docs/UNPKG_USAGE.md

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

# Using Spectrum Chat via unpkg CDN

## 📦 **Package Information**

- **Dev Package**: `@spectrumsense/spectrum-chat-dev`
- **Production Package**: `@spectrumsense/spectrum-chat`

Both packages are published with proper dist-tags for easy access.

---

## 🚀 **Development Package**

### **Option 1: Latest Version (Recommended)**
```html
<script src="https://unpkg.com/@spectrumsense/spectrum-chat-dev@latest/dist/spectrum-chat.js"></script>
```
✅ Always gets the newest published version  
✅ Updates automatically when new versions are published  
⚠️ May change without notice

### **Option 2: Dev Tag**
```html
<script src="https://unpkg.com/@spectrumsense/spectrum-chat-dev@dev/dist/spectrum-chat.js"></script>
```
✅ Points to the latest dev-tagged version  
✅ Same as `@latest` for dev packages  
⚠️ May change without notice

### **Option 3: Specific Version (Stable)**
```html
<script src="https://unpkg.com/@spectrumsense/spectrum-chat-dev@0.1.4-dev.1/dist/spectrum-chat.js"></script>
```
✅ Pinned to exact version  
✅ Won't change unexpectedly  
❌ Must manually update

### **Option 4: Version Range**
```html
<!-- Latest 0.1.x dev version -->
<script src="https://unpkg.com/@spectrumsense/spectrum-chat-dev@^0.1.0/dist/spectrum-chat.js"></script>
```
✅ Gets latest within range  
⚠️ May have breaking changes

---

## 🎯 **Production Package**

### **Latest Production Version**
```html
<script src="https://unpkg.com/@spectrumsense/spectrum-chat@latest/dist/spectrum-chat.js"></script>
```
✅ Stable production version  
✅ Only updates with production releases

### **Specific Production Version**
```html
<script src="https://unpkg.com/@spectrumsense/spectrum-chat@0.1.4/dist/spectrum-chat.js"></script>
```
✅ Pinned to exact production version

---

## 📋 **Which Should You Use?**

| Use Case | Recommended URL |
|----------|----------------|
| **Testing latest features** | `@spectrumsense/spectrum-chat-dev@latest` |
| **Development environment** | `@spectrumsense/spectrum-chat-dev@latest` |
| **Staging environment** | `@spectrumsense/spectrum-chat-dev@0.1.x-dev.x` (specific) |
| **Production website** | `@spectrumsense/spectrum-chat@latest` |
| **Production (stable)** | `@spectrumsense/spectrum-chat@0.1.4` (specific) |

---

## 🔍 **Finding Available Versions**

### Via npm:
```bash
# List all dev versions
npm view @spectrumsense/spectrum-chat-dev versions

# List all production versions
npm view @spectrumsense/spectrum-chat versions

# Check current tags
npm dist-tag ls @spectrumsense/spectrum-chat-dev
```

### Via unpkg:
Visit the package page to browse versions:
- Dev: https://unpkg.com/browse/@spectrumsense/spectrum-chat-dev/
- Prod: https://unpkg.com/browse/@spectrumsense/spectrum-chat/

### Via npm website:
- Dev: https://www.npmjs.com/package/@spectrumsense/spectrum-chat-dev
- Prod: https://www.npmjs.com/package/@spectrumsense/spectrum-chat

---

## 🛠️ **Manual Tag Management**

If you need to manually update tags (usually not needed):

```bash
# Update 'latest' tag to a specific version
npm dist-tag add @spectrumsense/spectrum-chat-dev@0.1.4-dev.1 latest

# Or use the script
npm run tag:latest
```

---

## ⚠️ **Troubleshooting**

### Issue: Getting 404 on unpkg
**Cause**: Version not yet synced to unpkg (takes 1-2 minutes)  
**Solution**: Wait a few minutes and try again

### Issue: Getting old/corrupted version
**Cause**: `latest` tag not updated  
**Solution**: 
```bash
npm dist-tag add @spectrumsense/spectrum-chat-dev@NEW_VERSION latest
```

### Issue: unpkg showing wrong version
**Cause**: CDN caching  
**Solutions**:
1. Wait a few minutes for cache to clear
2. Use specific version instead of `@latest`
3. Add cache-busting parameter: `?v=timestamp`
   ```html
   <script src="https://unpkg.com/@spectrumsense/spectrum-chat-dev@latest/dist/spectrum-chat.js?v=1234567890"></script>
   ```

### Issue: Browser caching old version
**Solution**: Hard refresh (Ctrl+Shift+R or Cmd+Shift+R)

---

## 📦 **Complete Example**

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Spectrum Chat Example</title>
</head>
<body>
  <h1>My Website</h1>

  <!-- For Development/Testing -->
  <script src="https://unpkg.com/@spectrumsense/spectrum-chat-dev@latest/dist/spectrum-chat.js"></script>

  <!-- OR for Production -->
  <!-- <script src="https://unpkg.com/@spectrumsense/spectrum-chat@latest/dist/spectrum-chat.js"></script> -->

  <script>
    window.SpectrumChatConfig = {
      apiUrl: 'https://dev-api.spectrumsense.co/api/v1/conversations',
      tenantId: 'your-tenant-id',
      title: 'AI Assistant',
      position: 'bottom-right'
    };
  </script>
</body>
</html>
```

---

## 🔄 **Automatic Updates**

Both manual publishing (`npm run publish:develop`) and GitHub Actions now automatically:

1. ✅ Publish with `--tag dev`
2. ✅ Update `latest` tag to point to the new version
3. ✅ Make it accessible via both `@latest` and `@dev`

This ensures unpkg URLs always work correctly! 🎉

---

## 📊 **Current Published Versions**

Check the current state:

```bash
# View all versions
npm view @spectrumsense/spectrum-chat-dev versions

# View current tags
npm dist-tag ls @spectrumsense/spectrum-chat-dev
```

Example output:
```
dev: 0.1.4-dev.1
latest: 0.1.4-dev.1
```

---

## 💡 **Best Practices**

1. ✅ Use `@latest` for development/testing
2. ✅ Use specific versions for production
3. ✅ Test with `@latest` before deploying specific version
4. ✅ Update production to specific version after testing
5. ❌ Don't use `@latest` in production if version stability is critical

---

**Need help?** Check the main documentation at `docs/README.md`