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

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

# Publishing Workflow Guide

This guide explains how to properly publish the Spectrum Chat package to npm for both production and development releases.

## Overview

We maintain **two separate npm packages**:
- **Production**: `@spectrumsense/spectrum-chat` - Stable releases
- **Development**: `@spectrumsense/spectrum-chat-dev` - Dev/testing releases

## Important Notes

⚠️ **CRITICAL**: The publishing scripts automatically:
1. Update the package name in `package.json` based on environment
2. Build the distribution files with the correct environment variables
3. Publish to the correct npm package

⚠️ **DO NOT** manually change the package name or version in `package.json` before publishing!

## Setup (One-time)

Make sure you're logged in to npm:
```bash
npm login
```

Verify you have access to both packages:
```bash
npm access ls-packages @spectrumsense
```

## Publishing Development Releases

### Step 1: Update Version (if needed)
```bash
# Bump to next dev version
npm run version:bump
```

This will bump the version following the pattern: `0.1.3` → `0.1.4-dev.0`

### Step 2: Publish to Dev
```bash
npm run publish:develop
```

This will:
1. ✅ Change package name to `@spectrumsense/spectrum-chat-dev`
2. ✅ Build with develop environment variables
3. ✅ Publish to npm with `dev` tag

### Step 3: Verify
Check your package on npm:
```
https://www.npmjs.com/package/@spectrumsense/spectrum-chat-dev
```

Test with unpkg:
```html
<script src="https://unpkg.com/@spectrumsense/spectrum-chat-dev@latest/dist/spectrum-chat.js"></script>
```

Or specific version:
```html
<script src="https://unpkg.com/@spectrumsense/spectrum-chat-dev@0.1.4-dev.0/dist/spectrum-chat.js"></script>
```

## Publishing Production Releases

### Step 1: Update Version
```bash
# For patch release (0.1.3 → 0.1.4)
npm version patch

# For minor release (0.1.3 → 0.2.0)
npm version minor

# For major release (0.1.3 → 1.0.0)
npm version major
```

### Step 2: Publish to Production
```bash
npm run publish:prod
```

This will:
1. ✅ Ensure package name is `@spectrumsense/spectrum-chat`
2. ✅ Build with production environment variables
3. ✅ Publish to npm with `latest` tag

### Step 3: Verify
Check your package on npm:
```
https://www.npmjs.com/package/@spectrumsense/spectrum-chat
```

Test with unpkg:
```html
<script src="https://unpkg.com/@spectrumsense/spectrum-chat@latest/dist/spectrum-chat.js"></script>
```

## Quick Reference

| Command | Purpose | Package Name | npm Tag |
|---------|---------|--------------|---------|
| `npm run publish:develop` | Publish dev release | `@spectrumsense/spectrum-chat-dev` | `dev` |
| `npm run publish:prod` | Publish production release | `@spectrumsense/spectrum-chat` | `latest` |
| `npm run version:bump` | Bump to next dev version | - | - |

## Versioning Strategy

### Development Versions
- Format: `MAJOR.MINOR.PATCH-dev.BUILD`
- Example: `0.1.4-dev.0`, `0.1.4-dev.1`, `0.1.4-dev.2`
- Tag: `dev`
- Use: Testing, development, preview deployments

### Production Versions
- Format: `MAJOR.MINOR.PATCH`
- Example: `0.1.3`, `0.1.4`, `0.2.0`
- Tag: `latest`
- Use: Production websites, stable releases

## Common Scenarios

### Scenario 1: Quick Dev Release
```bash
# If version already bumped in package.json
npm run publish:develop

# If need to bump version first
npm run version:bump
npm run publish:develop
```

### Scenario 2: Release to Production
```bash
# Update version
npm version patch  # or minor/major

# Publish
npm run publish:prod

# Tag in git
git push --tags
```

### Scenario 3: Multiple Dev Iterations
```bash
# First dev release
npm run version:bump
npm run publish:develop
# Published as 0.1.4-dev.0

# Second dev release (after more changes)
npm run version:bump
npm run publish:develop
# Published as 0.1.4-dev.1

# Third dev release
npm run version:bump
npm run publish:develop
# Published as 0.1.4-dev.2
```

### Scenario 4: Dev to Production
```bash
# You've been testing with dev releases
# Current version: 0.1.4-dev.2

# Ready for production
npm version patch
# Version is now 0.1.4

npm run publish:prod
# Published to @spectrumsense/spectrum-chat as 0.1.4
```

## Troubleshooting

### Error: Version already published
```
npm error 403 You cannot publish over the previously published versions
```

**Solution**: Bump the version first
```bash
npm run version:bump
npm run publish:develop
```

### Error: Package name mismatch
If you see the wrong package name in npm, it means the publish script wasn't used.

**Solution**: Always use the npm scripts:
- ✅ `npm run publish:develop`
- ✅ `npm run publish:prod`
- ❌ Don't use `npm publish` directly

### Error: Build failed on Windows
Make sure you're using PowerShell or Command Prompt, not WSL.

**Solution**: 
```bash
# Clean and rebuild
rmdir /s /q node_modules dist
npm install
npm run build:develop
```

### Corrupt files on unpkg
This usually means the build didn't run correctly before publishing.

**Solution**: 
```bash
# Clean rebuild
rm -rf dist
npm run build:develop  # or build:prod
```

The publish scripts now automatically run the build, so this shouldn't happen.

## File Structure After Publish

Your published package should include:
```
@spectrumsense/spectrum-chat-dev/
├── dist/
│   └── spectrum-chat.js       # UMD wrapped bundle
├── src/
│   └── spectrum-chat.js       # Source file
├── examples/                  # Example files
├── docs/                      # Documentation
├── package.json
├── README.md
└── LICENSE
```

## Environment Variables

The build process automatically sets these based on environment:

### Development (`publish:develop`)
```javascript
API_ROOT: 'https://dev-api.spectrumsense.co'
NODE_ENV: 'develop'
DEBUG: 'true'
PACKAGE_NAME: '@spectrumsense/spectrum-chat-dev'
```

### Production (`publish:prod`)
```javascript
API_ROOT: 'https://api.spectrumsense.co'
NODE_ENV: 'prod'
DEBUG: 'false'
PACKAGE_NAME: '@spectrumsense/spectrum-chat'
```

## Git Workflow Integration

### Recommended Git Workflow

1. **Feature branches** → publish to dev
   ```bash
   git checkout -b feature/new-feature
   # Make changes
   npm run version:bump
   npm run publish:develop
   git commit -am "feat: add new feature (v0.1.4-dev.0)"
   ```

2. **Merge to develop** → publish new dev version
   ```bash
   git checkout develop
   git merge feature/new-feature
   npm run version:bump
   npm run publish:develop
   ```

3. **Merge to main** → publish production
   ```bash
   git checkout main
   git merge develop
   npm version minor  # or patch/major
   npm run publish:prod
   git push --tags
   ```

## Best Practices

1. ✅ **Always use npm scripts** (`publish:develop`, `publish:prod`)
2. ✅ **Bump version before publishing** to avoid 403 errors
3. ✅ **Test dev releases** before promoting to production
4. ✅ **Keep package.json base state** as production (name: `@spectrumsense/spectrum-chat`)
5. ✅ **Use semantic versioning** (major.minor.patch)
6. ✅ **Tag production releases** in git
7. ❌ **Never manually edit** the package name before publishing
8. ❌ **Never use** `npm publish` directly (use the scripts)

## Quick Checklist

Before publishing development:
- [ ] Committed all changes
- [ ] Bumped version if needed (`npm run version:bump`)
- [ ] Run `npm run publish:develop`
- [ ] Verify on npm and unpkg

Before publishing production:
- [ ] Merged and tested in develop
- [ ] Updated version (`npm version patch/minor/major`)
- [ ] Run `npm run publish:prod`
- [ ] Verify on npm and unpkg
- [ ] Push tags to git
- [ ] Create GitHub release

## Support

If you encounter issues:
1. Check this guide first
2. Review the build scripts in `scripts/` directory
3. Check npm publish logs
4. Verify unpkg URL manually
5. Clean and rebuild if needed

---

**Remember**: The scripts handle everything automatically. Trust the process! 🚀