@crownpeak/dqm-react-component-dev-mcp 1.2.0

package/data/docs/NPM-PUBLISH.md

@@ -0,0 +1,193 @@
+## Prerequisites
+
+1. **NPM Account**: Ensure you have an account on [npmjs.com](https://www.npmjs.com/)
+2. **NPM Login**: Login to npm from your terminal:
+   ```bash
+   npm login
+   ```
+3. **Organization Access**: If publishing to `@crownpeak` scope, ensure you have write permissions to the organization
+
+## Pre-Publishing Checklist
+
+- [ ] Update version in `package.json` (follow [Semantic Versioning](https://semver.org/))
+- [ ] Update `CHANGELOG.md` with changes in this release
+- [ ] Ensure all tests pass: `npm test` (if tests exist)
+- [ ] Build succeeds: `npm run build`
+- [ ] Lint passes: `npm run lint`
+- [ ] Review package contents: `npm pack --dry-run`
+
+## Version Update
+
+Update the version number in `package.json`:
+
+```bash
+# For patches (bug fixes)
+npm version patch
+
+# For minor releases (new features, backwards compatible)
+npm version minor
+
+# For major releases (breaking changes)
+npm version major
+```
+
+This will automatically:
+- Update `package.json`
+- Create a git commit
+- Create a git tag
+
+## Publish to NPM
+
+### 1. First Time Publishing
+
+For first-time publishing of a scoped package:
+
+```bash
+npm publish --access public
+```
+
+### 2. Subsequent Publishes
+
+For regular updates:
+
+```bash
+npm publish
+```
+
+The `prepublishOnly` script will automatically:
+1. Run `npm run build` to compile all code
+2. Run `npm run lint` to check code quality
+
+### 3. Beta/Pre-release Versions
+
+For pre-release versions:
+
+```bash
+# Update to beta version
+npm version prerelease --preid=beta
+
+# Publish with beta tag
+npm publish --tag beta
+```
+
+Users can install with: `npm install @crownpeak/dqm-react-component@beta`
+
+## Post-Publishing
+
+1. **Push to Git**:
+   ```bash
+   git push origin main --follow-tags
+   ```
+
+2. **Create GitHub Release**:
+   - Go to GitHub repository
+   - Create a new release from the version tag
+   - Add release notes from `CHANGELOG.md`
+
+3. **Verify Installation**:
+   ```bash
+   npm view @crownpeak/dqm-react-component
+   ```
+
+4. **Test Installation**:
+   ```bash
+   npm install @crownpeak/dqm-react-component
+   ```
+
+## Package Contents
+
+The published package includes:
+
+- `dist/` - Compiled outputs
+   - `dist/index.js` - Library ESM build
+   - `dist/index.cjs` - Library CommonJS build
+   - `dist/index.d.ts` - Library type definitions
+   - `dist/dqm-widget.esm.js` - Standalone widget (ESM)
+   - `dist/dqm-widget.iife.js` - Standalone widget (IIFE)
+   - `dist/dqm-widget.d.ts` - Widget type definitions
+   - `dist/server/` - Backend server code
+   - `dist/auth-ui/` - Authentication UI bundle
+- `README.md` - Main documentation
+- `LICENSE` - MIT License
+- `CHANGELOG.md` - Version history
+- `QUICKSTART.md` - Quick start guide
+- `EXAMPLES.md` - Usage examples
+- `AUTHENTICATION.md` - Auth documentation
+- `BACKEND-API.md` - Backend API docs
+- `DEVELOPMENT.md` - Development guide
+- `PUBLISHING.md` - Publishing workflow
+
+## Files Excluded (via .npmignore)
+
+- Source code (`src/`, `server/`, `server-ui/`)
+- Development files (`.vscode/`, `.env`, config files)
+- Build configuration files
+- Test files
+- Git files
+
+## Unpublishing
+
+⚠️ **Caution**: Unpublishing is discouraged and only allowed within 72 hours.
+
+```bash
+npm unpublish @crownpeak/dqm-react-component@1.0.0
+```
+
+## Deprecating a Version
+
+If a version has issues, deprecate it instead of unpublishing:
+
+```bash
+npm deprecate @crownpeak/dqm-react-component@1.0.0 "Critical bug, use version 1.0.1 instead"
+```
+
+## Troubleshooting
+
+### Authentication Errors
+
+```bash
+npm logout
+npm login
+```
+
+### Permission Errors
+
+Ensure you have write access to the `@crownpeak` organization on npmjs.com.
+
+### Build Errors
+
+Clean and rebuild:
+
+```bash
+rm -rf dist node_modules
+npm install
+npm run build
+```
+
+### Package Size Warnings
+
+Check bundle size:
+
+```bash
+npm pack --dry-run | grep "unpacked size"
+```
+
+Current package size: ~4.3 MB unpacked, ~1.2 MB packed
+
+## NPM Scripts Reference
+
+- `npm run build` - Build library, widget, server, and auth-ui
+- `npm run build:lib` - Build library only
+- `npm run build:widget` - Build standalone widget bundles + copy types
+- `npm run build:server` - Build server only
+- `npm run build:auth-ui` - Build auth-ui only
+- `npm run lint` - Run ESLint
+- `npm pack` - Create tarball locally for testing
+- `npm publish` - Publish to npm registry
+
+## Resources
+
+- [NPM Publishing Docs](https://docs.npmjs.com/cli/v10/commands/npm-publish)
+- [Semantic Versioning](https://semver.org/)
+- [NPM Package Scope](https://docs.npmjs.com/cli/v10/using-npm/scope)
+- [NPM Organizations](https://docs.npmjs.com/organizations)

package/data/docs/QUICKSTART.md

@@ -0,0 +1,206 @@
+## Installation
+
+```bash
+npm install
+```
+
+## Build
+
+```bash
+npm run build
+```
+
+### Build widget only (for standalone script usage)
+
+```bash
+npm run build:widget
+npm run serve:widget   # preview demos at http://localhost:4173/test/demo-iife.html etc.
+```
+
+## Start Development
+
+```bash
+npm run dev        # Vite dev server with integrated backend (port 5173)
+npm run dev:server # Standalone Express server with Redis (port 3001)
+```
+
+This starts:
+- ✅ **Frontend + Backend**: http://localhost:5173 (Vite Dev Server with integrated backend API)
+- Backend routes (`/auth/*`, `/dqm/*`) are handled by Vite plugin
+
+## Test the Integration
+
+### 1. Open Frontend
+Navigate to http://localhost:5173
+
+### 2. Configure Backend Mode
+The test harness is already configured to use the backend:
+
+```tsx
+config={{
+  authBackendUrl: '', // Empty = same origin (backend integrated in Vite dev server)
+  useLocalStorage: true,
+}}
+```
+
+### 3. Login with Credentials
+- Enter your Crownpeak DQM API Key
+- Enter your Website ID
+- Click "Continue"
+
+The backend will:
+1. Validate credentials with Crownpeak DQM API
+2. Issue a session token
+3. Store token in localStorage
+
+### 4. Analyze HTML
+- Paste HTML in the editor
+- Click "Start Analysis"
+- All requests go through `/dqm/*` on the same origin (port 5173 in dev)
+
+## Architecture
+
+```mermaid
+graph LR
+A[React App + Backend API<br/>Port 5173]
+B[Vite Dev Server<br/>with integrated backend]
+C[Crownpeak DQM<br/>API]
+
+    A -->|HTTP Requests| B
+    B -->|Proxied Requests| C
+    
+    A -.->|sessionToken<br/>localStorage| A
+    B -.->|apiKey + websiteId<br/>in-memory · Redis-ready| B
+    
+    subgraph Frontend
+        A
+        A1[DQMSidebar]
+        A2[Login UI]
+        A3[HTML Editor]
+    end
+    
+    subgraph Backend
+        B
+        B1[Auth Routes]
+        B2[DQM Proxy]
+        B3[Sessions]
+    end
+    
+    subgraph External
+        C
+        C1[Analysis]
+        C2[Highlights]
+        C3[Checkpoints]
+    end
+```
+
+## Two Authentication Modes
+
+### Backend Mode (Recommended)
+```tsx
+config={{
+  authBackendUrl: '', // Dev: empty (same origin) | Prod: 'https://your-backend.com'
+}}
+```
+- ✅ Secure session tokens
+- ✅ API keys remain server-side
+- ✅ Centralized access control
+
+### Direct Mode (Development)
+```tsx
+config={{
+  apiKey: 'YOUR_API_KEY',
+  websiteId: 'YOUR_WEBSITE_ID',
+}}
+```
+- ✅ No backend required
+- ✅ Quick testing
+- ✅ Props or localStorage
+
+## API Endpoints
+
+### Authentication
+- `POST /auth/login` - Login with credentials
+- `POST /auth/logout` - Invalidate session
+- `GET /auth/session` - Get session info
+
+### DQM Proxy
+- `POST /dqm/assets` - Start analysis
+- `GET /dqm/assets/:id` - Get results
+- `GET /dqm/assets/:id/pagehighlight/all` - All highlights
+- `GET /dqm/assets/:id/pagehighlight/:cpId` - Single highlight
+
+All DQM endpoints require `Authorization: Bearer <sessionToken>`
+
+## Scripts
+
+```bash
+# Development
+npm run dev              # Vite dev server with integrated backend (port 5173)
+npm run dev:client       # Same as npm run dev
+npm run dev:server       # Standalone Express server with Redis (port 3001)
+
+# Build
+npm run build            # Build all
+npm run build:lib        # Build React library
+npm run build:server     # Build Express server
+
+# Production
+npm run start:server     # Run built server
+```
+
+## Environment Setup
+
+Copy `.env.example` to `.env`:
+
+```env
+PORT=3001
+CORS_ORIGINS=http://localhost:5173
+DQM_API_BASE_URL=https://api.crownpeak.net/dqm-cms/v1
+JWT_SECRET=your-secret-key
+```
+
+## Documentation
+
+- **[BACKEND-API.md](./BACKEND-API.md)** - Backend API specification
+- **[DEVELOPMENT.md](./DEVELOPMENT.md)** - Development guide
+- **[server/README.md](./server/README.md)** - Server documentation
+- **[AUTHENTICATION.md](./AUTHENTICATION.md)** - Auth flow details
+- **[EXAMPLES.md](./EXAMPLES.md)** - Integration examples
+
+## Testing
+
+### Test Backend Health (Dev Mode - Port 5173)
+```bash
+curl http://localhost:5173/health
+```
+
+### Test Login (Dev Mode)
+```bash
+curl -X POST http://localhost:5173/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"apiKey":"YOUR_KEY","websiteId":"YOUR_ID"}'
+```
+
+### Test Analysis (Dev Mode)
+```bash
+curl -X POST http://localhost:5173/dqm/assets \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"html":"<html><body>Test</body></html>"}'
+```
+
+## Features
+
+✅ **Modular Backend** - Express.js with clean architecture  
+✅ **Session Management** - In-memory store (Redis-ready)  
+✅ **DQM API Proxy** - All analysis endpoints  
+✅ **CORS & Security** - Helmet.js, CORS whitelist  
+✅ **Auto-reload** - TSX watch mode for development  
+✅ **Concurrent Servers** - Frontend + Backend in one command  
+✅ **TypeScript** - Full type safety  
+✅ **Error Handling** - Centralized middleware  
+
+## License
+
+MIT

package/data/docs/REDIS-SETUP.md

@@ -0,0 +1,162 @@
+## Problem
+
+The backend uses **In-Memory Sessions** by default. These are lost on every server restart, which means:
+- Users must log in again after every deployment
+- Development with hot-reload causes frequent session losses
+- Load-balancing across multiple servers doesn't work
+
+## Solution: Redis
+
+Redis stores sessions persistently and across servers. Sessions survive:
+- ✅ Server restarts
+- ✅ Deployments
+- ✅ Load balancing
+- ✅ Hot-reload during development
+
+## Quick Start
+
+### Local Development (Docker)
+
+```bash
+# Start Redis
+docker run -d -p 6379:6379 redis:alpine
+
+# Set environment variable
+export REDIS_URL=redis://localhost:6379
+
+# Start server
+npm run dev:server
+```
+
+### Local Development (without Docker)
+
+```bash
+# macOS
+brew install redis
+redis-server
+
+# Ubuntu/Debian
+sudo apt-get install redis-server
+sudo systemctl start redis-server
+
+# Set environment variable
+export REDIS_URL=redis://localhost:6379
+
+# Start server
+npm run dev:server
+```
+
+### Production Deployment
+
+#### Option 1: Redis Cloud (Managed, Free Tier available)
+
+1. Create an account on [Redis Cloud](https://redis.com/try-free/)
+2. Create a new database
+3. Copy the connection string
+4. Set environment variable:
+
+```bash
+REDIS_URL=redis://default:password@redis-xxxxx.redislabs.com:xxxxx
+```
+
+#### Option 2: AWS ElastiCache
+
+```bash
+REDIS_URL=redis://your-elasticache-cluster.xxxxx.cache.amazonaws.com:6379
+```
+
+#### Option 3: Azure Cache for Redis
+
+```bash
+REDIS_URL=redis://:password@your-cache.redis.cache.windows.net:6380?tls=true
+```
+
+#### Option 4: Heroku Redis
+
+```bash
+# Automatically set via REDIS_URL env var
+heroku addons:create heroku-redis:mini
+```
+
+## Fallback Behavior
+
+When **no Redis connection** is available:
+- ⚠️ Automatic fallback to in-memory storage
+- ⚠️ Warning log: "Redis not available, using in-memory storage"
+- ⚠️ Sessions are lost on server restart
+
+## Monitoring
+
+The backend logs show:
+```
+[SessionStore] ✅ Connected to Redis
+[SessionStore] Created Redis session: a285dde5... (expires in 1440 minutes)
+[Auth] Current sessions in store: 5 (storage: redis)
+```
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# .env
+REDIS_URL=redis://localhost:6379
+
+# Optional Redis configuration
+REDIS_PASSWORD=your-password
+REDIS_TLS=true  # For production with TLS
+```
+
+### Session TTL
+
+Sessions expire after 24 hours (configurable in `server/config.ts`):
+
+```typescript
+session: {
+  ttl: 24 * 60 * 60 * 1000, // 24 hours in milliseconds
+}
+```
+
+## Troubleshooting
+
+### "Redis connection failed"
+- Check if Redis is running: `redis-cli ping` → should return "PONG"
+- Check REDIS_URL format
+- Check firewall/security groups
+
+### "Session expired" despite Redis
+- TTL might be too short → Increase in `config.ts`
+- Redis memory full → Check `redis-cli info memory`
+
+### Sessions are not being saved
+- Check backend logs: Should show "Created Redis session"
+- Check Redis: `redis-cli KEYS "session:*"`
+
+## Best Practices
+
+### Development
+```bash
+# Local Redis, no persistence needed
+docker run -d -p 6379:6379 redis:alpine
+```
+
+### Staging/Production
+```bash
+# Managed Redis with backups and monitoring
+# Redis Cloud, AWS ElastiCache, Azure Cache
+```
+
+### Security
+- ✅ Use TLS in production (`rediss://` instead of `redis://`)
+- ✅ Use strong passwords
+- ✅ Restrict network access (security groups)
+- ✅ Enable Redis AUTH
+
+## Migration from In-Memory to Redis
+
+No code changes required! Simply:
+1. Set REDIS_URL environment variable
+2. Restart server
+3. Backend automatically detects Redis
+
+Existing sessions are lost during migration (users must log in again).