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

package/data/docs/TROUBLESHOOTING.md

@@ -0,0 +1,657 @@
+Solutions for common issues with `@crownpeak/dqm-react-component`.
+
+## Table of Contents
+- [FAQ](#faq)
+- [Error Messages](#error-messages)
+- [AI Features Issues](#ai-features-issues)
+- [Browser Compatibility](#browser-compatibility)
+- [Performance Issues](#performance-issues)
+- [Debugging Tools](#debugging-tools)
+
+## FAQ
+
+### General
+
+#### Q: Sidebar not showing after installation?
+
+**A:** Check these common issues:
+
+1. **Authentication**: Verify `apiKey` and `websiteId` are set
+2. **Component State**: Ensure `open` prop is set to `true` or FAB button is clicked
+3. **CSS Conflicts**: Check if global styles hide or break sidebar
+4. **Browser Console**: Look for errors in console
+
+```typescript
+// Verify authentication
+console.log('API Key:', localStorage.getItem('dqm_apiKey'));
+console.log('Website ID:', localStorage.getItem('dqm_websiteID'));
+
+// Force open sidebar
+<DQMSidebar
+    open={true}  // Force open for testing
+    onOpen={...}
+    onClose={...}
+/>
+```
+
+---
+
+#### Q: How do I know which authentication mode is active?
+
+**A:** Use `onAuthSuccess` callback to inspect session type:
+
+```typescript
+<DQMSidebar
+    open={open}
+    onOpen={() => setOpen(true)}
+    onClose={() => setOpen(false)}
+    onAuthSuccess={(credentials) => {
+        console.log('Session Type:', credentials.sessionType);
+        // 'direct' = Direct DQM API calls
+        // 'backend' = Proxy via backend server
+    }}
+/>
+```
+
+---
+
+#### Q: Can I use DQM without React?
+
+**A:** Yes! Use the standalone widget bundle (IIFE or ESM):
+
+```html
+<script src="https://unpkg.com/@crownpeak/dqm-react-component/dist/dqm-widget.iife.js"></script>
+<script>
+    window.DQMWidget.loadDQMWidget({
+        config: {
+            websiteId: 'your-website-id',
+            apiKey: 'your-api-key',
+        }
+    });
+</script>
+```
+
+See **[Widget Guide](./WIDGET-GUIDE.md)** for details.
+
+---
+
+#### Q: How do I disable DQM in production?
+
+**A:** Use the `disabled` config property:
+
+```typescript
+<DQMSidebar
+    open={open}
+    onOpen={...}
+    onClose={...}
+    config={{
+        disabled: process.env.NODE_ENV === 'production',
+    }}
+/>
+```
+
+Or conditionally render:
+
+```typescript
+{process.env.NODE_ENV === 'development' && (
+    <DQMSidebar open={open} onOpen={...} onClose={...} />
+)}
+```
+
+---
+
+#### Q: Can I customize sidebar styles?
+
+**A:** No, the sidebar uses Shadow DOM for style isolation. Styles are bundled and cannot be overridden. This ensures consistent rendering across all environments.
+
+---
+
+### AI Features
+
+#### Q: Why is translation not working?
+
+**A:** Check these requirements:
+
+1. **Enabled**: `translation.enabled` must be `true`
+2. **API Key**: Valid OpenAI `apiKey` (starts with `sk-`)
+3. **Model**: Check model name is correct
+4. **Target Language**: Valid ISO 639-1 code (e.g., `'de'`, `'es'`, `'fr'`)
+
+```typescript
+config={{
+    translation: {
+        enabled: true,              // MUST be true
+        apiKey: 'sk-...',           // Valid OpenAI API key
+        model: 'gpt-4o-mini',       // Correct model name
+        targetLanguage: 'de',       // ISO 639-1 code
+        mode: 'fast',
+    },
+}}
+```
+
+**Debug:**
+```typescript
+// Check localStorage settings
+console.log('Translation Enabled:', localStorage.getItem('dqm_translate_results_enabled'));
+console.log('Target Language:', localStorage.getItem('dqm_target_language'));
+console.log('OpenAI API Key Set:', !!localStorage.getItem('dqm_openai_apiKey'));
+```
+
+---
+
+#### Q: Translation taking too long?
+
+**A:** Try these optimizations:
+
+1. **Switch to Fast Mode**: `mode: 'fast'` (15s timeout vs 120s for `'full'`)
+2. **Use a faster model**: `gpt-4o-mini` is optimized for speed
+
+```typescript
+// Optimize for speed
+translation: {
+    enabled: true,
+    apiKey: 'sk-...',
+    model: 'gpt-4o-mini',       // Fast + cheap
+    targetLanguage: 'de',
+    mode: 'fast',               // 15s timeout
+}
+```
+
+---
+
+#### Q: Summary generation failing?
+
+**A:** Check these:
+
+1. **OpenAI API Key**: Summary requires valid OpenAI key
+2. **Model**: Ensure model supports JSON mode (`gpt-4o-mini`, `gpt-4o`, `gpt-4.1`)
+3. **Timeout**: Increase timeout if analysis has many checkpoints
+
+```typescript
+config={{
+    summary: {
+        enabled: true,
+        backend: 'openai',          // Only OpenAI supported
+        apiKey: 'sk-...',           // Valid key
+        model: 'gpt-4o-mini',       // Supported model
+        timeoutMs: 60000,           // Increase timeout for large analyses
+    },
+}}
+```
+
+---
+
+#### Q: How do I clear AI cache?
+
+**A:** Clear IndexedDB cache:
+
+```javascript
+// Clear translation cache
+indexedDB.deleteDatabase('DQMTranslationCache');
+
+// Reload page
+window.location.reload();
+```
+
+Or use browser DevTools:
+1. Open DevTools (F12)
+2. Go to "Application" tab
+3. Click "IndexedDB" → "DQMTranslationCache"
+4. Right-click → "Delete database"
+
+---
+
+### Internationalization
+
+#### Q: How do I change sidebar language?
+
+**A:** Set `dqm_locale` in localStorage:
+
+```typescript
+// Change to German
+localStorage.setItem('dqm_locale', 'de');
+
+// Reload to apply
+window.location.reload();
+```
+
+Or use i18next directly:
+
+```typescript
+import { useTranslation } from 'react-i18next';
+
+function MyComponent() {
+    const { i18n } = useTranslation();
+    
+    return (
+        <button onClick={() => i18n.changeLanguage('de')}>
+            Deutsch
+        </button>
+    );
+}
+```
+
+**Supported Languages:** `en`, `de`, `es`
+
+---
+
+## Error Messages
+
+### Authentication Errors
+
+#### `AUTH_001: Invalid API Key`
+
+**Cause:** API key is invalid or expired.
+
+**Solution:**
+1. Verify API key is correct (check for typos)
+2. Check API key hasn't been revoked in Crownpeak DQM admin
+3. Ensure API key has access to specified website ID
+
+```typescript
+// Verify credentials
+console.log('API Key:', localStorage.getItem('dqm_apiKey'));
+console.log('Website ID:', localStorage.getItem('dqm_websiteID'));
+```
+
+---
+
+#### `AUTH_002: Website ID Not Found`
+
+**Cause:** Website ID doesn't exist or API key doesn't have access.
+
+**Solution:**
+1. Verify website ID is correct
+2. Check API key has permission for this website
+3. Contact Crownpeak support if issue persists
+
+---
+
+#### `AUTH_003: Backend Server Unreachable`
+
+**Cause:** Backend server (authentication proxy) is down or URL is incorrect.
+
+**Solution:**
+1. Verify `authBackendUrl` is correct
+2. Check backend server is running
+3. Check CORS configuration on backend
+
+```typescript
+// Test backend connectivity
+fetch('https://your-backend.com/auth/session')
+    .then(res => res.json())
+    .then(data => console.log('Backend reachable:', data))
+    .catch(err => console.error('Backend unreachable:', err));
+```
+
+---
+
+### Translation Errors
+
+#### `TRANSLATION_001: OpenAI API Key Invalid`
+
+**Cause:** OpenAI API key is invalid or quota exceeded.
+
+**Solution:**
+1. Verify API key is correct (starts with `sk-`)
+2. Check OpenAI account has credits
+3. Verify API key hasn't been revoked
+
+```typescript
+// Test OpenAI API key
+fetch('https://api.openai.com/v1/models', {
+    headers: { 'Authorization': `Bearer sk-...` }
+})
+    .then(res => res.json())
+    .then(data => console.log('OpenAI API working:', data))
+    .catch(err => console.error('OpenAI API error:', err));
+```
+
+---
+
+#### `TRANSLATION_003: Translation Timeout`
+
+**Cause:** Translation took longer than configured timeout.
+
+**Solution:**
+1. Switch from `'full'` to `'fast'` mode
+2. Reduce number of checkpoints (if applicable)
+
+```typescript
+// Optimize for speed
+translation: {
+    apiKey: 'sk-...',
+    model: 'gpt-4o-mini',
+    targetLanguage: 'de',
+    mode: 'fast',  // 15s timeout instead of 120s
+}
+```
+
+---
+
+### Summary Errors
+
+#### `SUMMARY_001: OpenAI API Error`
+
+**Cause:** OpenAI API request failed (rate limit, quota, network).
+
+**Solution:**
+1. Check OpenAI account credits
+2. Verify API key permissions
+3. Check rate limits (tier-based)
+
+---
+
+#### `SUMMARY_002: Chunking Strategy Failed`
+
+**Cause:** Too many checkpoints, chunking strategy couldn't complete.
+
+**Solution:**
+1. Increase timeout: `summary.timeoutMs: 90000`
+2. Reduce checkpoint count (filter failed only)
+3. Use simpler model (`gpt-4o-mini` instead of `gpt-4o`)
+
+---
+
+### Analysis Errors
+
+#### `ANALYSIS_001: DQM API Timeout`
+
+**Cause:** DQM API took too long to analyze HTML.
+
+**Solution:**
+1. Reduce HTML complexity (remove unnecessary elements)
+2. Check HTML size (<1MB recommended)
+3. Try again (transient error)
+
+---
+
+#### `ANALYSIS_002: Invalid HTML`
+
+**Cause:** HTML contains syntax errors preventing analysis.
+
+**Solution:**
+1. Validate HTML with W3C Validator
+2. Check for unclosed tags
+3. Remove invalid characters
+
+---
+
+## AI Features Issues
+
+### Performance
+
+| Checkpoint Count | Translation Time |
+|-----------------|------------------|
+| 10 | 2-3s |
+| 50 | 5-8s |
+| 100 | 10-15s |
+
+**Note:** Times assume good network connection. Cached checkpoints: instant (0ms).
+
+### Caching Issues
+
+#### Cache Not Working?
+
+**Symptoms:** Translation re-runs every time even with same checkpoints.
+
+**Cause:** IndexedDB cache disabled or cleared.
+
+**Solution:**
+1. Verify IndexedDB works in browser
+2. Check browser storage quota
+3. Enable IndexedDB cache in config
+
+```typescript
+// Check IndexedDB support
+if ('indexedDB' in window) {
+    console.log('IndexedDB supported');
+} else {
+    console.error('IndexedDB not supported - caching disabled');
+}
+```
+
+---
+
+#### Cache Taking Too Much Space?
+
+**Symptoms:** Browser storage quota exceeded.
+
+**Solution:** Clear old cache entries:
+
+```javascript
+// Clear translation cache
+indexedDB.deleteDatabase('DQMTranslationCache');
+
+// Cache will rebuild on next translation
+```
+
+---
+
+## Browser Compatibility
+
+### React Version Compatibility
+
+| React Version | Compatible | Notes |
+|---------------|------------|-------|
+| 18.x | ✅ Yes | Recommended |
+| 17.x | ⚠️ Partial | Some features may not work |
+| 16.x | ❌ No | Not supported |
+
+---
+
+### Material-UI Version Compatibility
+
+| MUI Version | Compatible | Notes |
+|-------------|------------|-------|
+| 5.x | ✅ Yes | Recommended |
+| 4.x | ❌ No | Not supported |
+
+---
+
+## Performance Issues
+
+### Sidebar Loading Slowly?
+
+**Symptoms:** Sidebar takes 5+ seconds to open.
+
+**Possible Causes:**
+1. Large HTML document (>1MB)
+2. Slow DQM API response
+3. AI features enabled with slow backend
+
+**Solutions:**
+
+```typescript
+// 1. Optimize HTML before analysis
+const optimizedHtml = document.documentElement.outerHTML
+    .replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, '') // Remove scripts
+    .replace(/<style\b[^<]*(?:(?!<\/style>)<[^<]*)*<\/style>/gi, '');    // Remove styles
+
+// 2. Disable AI features for faster loading
+<DQMSidebar
+    open={open}
+    onOpen={...}
+    onClose={...}
+    config={{
+        websiteId: '...',
+        apiKey: '...',
+        // translation: { enabled: false },  // Disable for faster loading
+        // summary: { enabled: false },
+    }}
+/>
+
+// 3. Use fast mode for AI translation
+translation: {
+    enabled: true,
+    apiKey: 'sk-...',
+    model: 'gpt-4o-mini',
+    targetLanguage: 'de',
+    mode: 'fast',  // 15s timeout instead of 120s
+}
+```
+
+---
+
+### High Memory Usage?
+
+**Symptoms:** Browser tab uses excessive memory.
+
+**Possible Causes:**
+1. Large IndexedDB cache
+2. Many cached highlight renderings
+
+**Solutions:**
+
+```typescript
+// Clear cache periodically
+indexedDB.deleteDatabase('DQMTranslationCache');
+```
+
+---
+
+## Debugging Tools
+
+### Enable Debug Logging
+
+```typescript
+// Method 1: Via localStorage
+localStorage.setItem('dqm_debug', 'true');
+window.location.reload();
+
+// Method 2: Via logger (if using library export)
+import { logger } from '@crownpeak/dqm-react-component';
+logger.setDebugMode(true);
+```
+
+**Log Format:**
+```
+[DQM] [DEBUG] Analysis started
+[DQM] [WARN] Translation timeout (15s)
+[DQM] [ERROR] API request failed: 401 Unauthorized
+```
+
+---
+
+### Inspect localStorage
+
+```javascript
+// View all DQM settings
+Object.keys(localStorage)
+    .filter(key => key.startsWith('dqm_'))
+    .forEach(key => {
+        console.log(key, '=', localStorage.getItem(key));
+    });
+```
+
+**Expected Keys:**
+- `dqm_apiKey` - DQM API key
+- `dqm_websiteID` - Website ID
+- `dqm_translate_results_enabled` - Translation toggle
+- `dqm_target_language` - Target language
+- `dqm_ai_summary_enabled` - Summary toggle
+- `dqm_openai_apiKey` - OpenAI API key
+- `dqm_openai_model` - OpenAI model name
+- `dqm_locale` - UI language
+- `dqm_debug` - Debug mode
+
+---
+
+### Inspect IndexedDB
+
+1. Open DevTools (F12)
+2. Go to "Application" tab
+3. Click "IndexedDB" → "DQMTranslationCache"
+4. View cached translations
+
+**Cache Structure:**
+```javascript
+{
+    key: 'fnv1a_hash_of_checkpoint',
+    value: {
+        originalText: 'Original checkpoint description',
+        translatedText: 'Übersetzter Checkpoint-Text',
+        targetLanguage: 'de',
+        timestamp: 1234567890,
+    }
+}
+```
+
+---
+
+### Network Inspection
+
+**DQM API Calls:**
+1. Open DevTools (F12) → "Network" tab
+2. Filter by "dqm" or "api.crownpeak.net"
+3. Check request/response:
+   - **POST /assets**: HTML analysis request
+   - **GET /assets/{id}**: Poll for analysis result
+   - **GET /assets/{id}/pagehighlight/{checkpointId}**: Fetch highlighted HTML
+
+**OpenAI API Calls:**
+1. Filter by "api.openai.com"
+2. Check requests:
+   - **POST /v1/chat/completions**: Translation or summary request
+   - Response should have `choices[0].message.content`
+
+---
+
+### Redux DevTools
+
+Install Redux DevTools Extension:
+- [Chrome](https://chrome.google.com/webstore/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd)
+- [Firefox](https://addons.mozilla.org/en-US/firefox/addon/reduxdevtools/)
+
+**Inspect State:**
+1. Open DevTools → "Redux" tab
+2. View state tree:
+   - `auth` - Authentication state
+   - `ai` - AI translation/summary state
+   - `highlight` - Error highlight navigation
+   - `locale` - UI language
+
+---
+
+### React DevTools
+
+Install React DevTools Extension:
+- [Chrome](https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi)
+- [Firefox](https://addons.mozilla.org/en-US/firefox/addon/react-devtools/)
+
+**Inspect Components:**
+1. Open DevTools → "Components" tab
+2. Find `DQMSidebar` component
+3. View props and state
+
+---
+
+## Getting Help
+
+### Before Opening an Issue
+
+1. **Enable Debug Logging**: `localStorage.setItem('dqm_debug', 'true')`
+2. **Check Browser Console**: Look for error messages
+3. **Inspect Network Tab**: Verify API calls are successful
+4. **Review localStorage**: Ensure credentials are set
+5. **Test in Incognito**: Rule out extension conflicts
+
+### Include in Bug Reports
+
+- **Browser**: Chrome 120.0.6099.109
+- **React Version**: 18.2.0
+- **MUI Version**: 5.14.0
+- **Component Version**: 1.2.0
+- **Error Message**: Full error from console
+- **Steps to Reproduce**: Minimal code example
+- **Expected vs Actual**: What you expected vs what happened
+
+---
+
+## See Also
+
+- **[Examples](./EXAMPLES.md)** - Integration examples
+- **[AI Features Guide](./AI-FEATURES.md)** - AI documentation
+- **[API Reference](./API-REFERENCE.md)** - TypeScript API
+- **[Migration Guide](./MIGRATION-GUIDE.md)** - Upgrade from v1.1 to v1.2
+- **[GitHub Issues](https://github.com/e-Spirit/crownpeak-dqm-react-component/issues)** - Report bugs