@courseecho/ai-widget-angular 1.0.0

package/DEPRECATION_NOTICE.md

@@ -0,0 +1,93 @@
+# ⚠️ DEPRECATION NOTICE
+
+## Status: CONSOLIDATED
+
+The **@courseecho/ai-widget-angular** package (in this directory) is now the official Angular implementation.
+
+### What Changed?
+
+| Aspect | Before | Now |
+|--------|--------|-----|
+| Angular Support | 14-17 | **19+** (modern only) |
+| Syntax | `*ngIf`, `*ngFor` | **@if, @for** (new control flow) |
+| Version | Multi-version | **Single version** |
+| Purpose | Standalone | **Part of unified SDK** |
+
+### Old Package Location
+
+**DEPRECATED:** `courseecho-bot-fe/projects/ai-widget-sdk/`
+
+This old package is being deprecated in favor of the unified multi-framework approach.
+
+### Migration Guide
+
+If you were using the old **@courseecho/ai-widget-sdk** from npm:
+
+```bash
+# Old (deprecated)
+npm uninstall @courseecho/ai-widget-sdk
+
+# New (recommended)
+npm install @courseecho/ai-widget-angular
+```
+
+The API is similar but improved. See [README.md](./README.md) for details.
+
+### Why Consolidate?
+
+✅ **Unified Ecosystem** - Same API as React, Vue, Node.js packages  
+✅ **Modern Angular** - Uses Angular 19+ with latest syntax  
+✅ **Better Maintenance** - Single source of truth  
+✅ **Consistency** - All frameworks follow same pattern  
+✅ **Smaller Bundle** - Optimized for modern Angular  
+
+### What's the Same?
+
+- ✅ Floating chat widget
+- ✅ Message history
+- ✅ Authentication (JWT, API key)
+- ✅ Context tracking
+- ✅ Export functionality
+
+### What's Different?
+
+| Feature | Old | New |
+|---------|-----|-----|
+| Chart Rendering | ✅ Built-in | 📊 Via backend |
+| Control Flow | Traditional | Modern (@if, @for) |
+| Angular Versions | 14+ | 19+ only |
+| Bundle Size | 40KB | 18KB |
+| Multi-framework API | ❌ | ✅ |
+
+### Chart Support in New Version?
+
+Charts are still available! They come from:
+1. **Backend responses** - AI returns chart data
+2. **Widget displays them** - Using standard HTML/canvas
+3. **Libraries optional** - No Chart.js dependency required
+
+### Still Need the Old One?
+
+If you **absolutely must** use the old one with Angular 14-18:
+
+```bash
+# Temporary: Access from bot-fe
+npm install courseecho-bot-fe/projects/ai-widget-sdk
+```
+
+But we recommend upgrading to Angular 19+ and using the new unified package.
+
+### Timeline
+
+- **Now:** Old package marked deprecated
+- **v1.1:** Old package removed from npm
+- **v2.0:** Old package archive only (no support)
+
+### Questions?
+
+See [README.md](./README.md) or check the [main product guide](../PRODUCT_OVERVIEW.md).
+
+---
+
+**Recommendation:** Migrate to the new @courseecho/ai-widget-angular package for best experience! 🚀
+

package/README.md

@@ -0,0 +1,624 @@
+# @courseecho/ai-widget-angular
+
+AI Chat Widget for Angular 14+. Beautiful, production-ready component and service for integrating intelligent chat capabilities into your Angular applications.
+
+## ✨ Features
+
+- 🎨 **Beautiful Floating Widget** - Professional, customizable chat interface
+- 🚀 **Angular 19+** - Modern Angular 19+ with latest control flow syntax (@if, @for)
+- 🔐 **Secure Authentication** - JWT and API key support
+- 💬 **Advanced Chat** - Message history, source attribution, follow-up suggestions
+- 📊 **Data Visualization** - Support for charts and data display
+- 🎯 **Context Aware** - Automatic page context tracking
+- 📱 **Responsive** - Works on mobile, tablet, desktop
+- 📦 **Type-Safe** - Full TypeScript support
+- ⚡ **Optimized** - ~18KB bundle, minimal dependencies
+
+## 📦 Installation
+
+### Prerequisites
+- Angular 19+
+- RxJS 7.8+
+- Node.js 18+
+
+### Step 1: Install Core SDK (Required)
+```bash
+npm install @courseecho/ai-core-sdk
+```
+
+### Step 2: Install Angular Widget
+```bash
+npm install @courseecho/ai-widget-angular
+```
+
+## 🚀 Quick Start (5 Minutes)
+
+### Option 1: Module-based (Traditional Angular)
+
+```typescript
+import { NgModule } from '@angular/core';
+import { BrowserModule } from '@angular/platform-browser';
+import { AiWidgetModule } from '@courseecho/ai-widget-angular';
+import { AppComponent } from './app.component';
+
+@NgModule({
+  declarations: [AppComponent],
+  imports: [BrowserModule, AiWidgetModule],
+  bootstrap: [AppComponent]
+})
+export class AppModule { }
+```
+
+```typescript
+import { Component } from '@angular/core';
+import { AiWidgetConfig, AiAuthConfig } from '@courseecho/ai-widget-angular';
+
+@Component({
+  selector: 'app-root',
+  template: `
+    <app-ai-chat-widget [config]="config" [authConfig]="authConfig"></app-ai-chat-widget>
+  `
+})
+export class AppComponent {
+  config: AiWidgetConfig = {
+    apiEndpoint: 'http://localhost:5000',
+    enableFloatingButton: true,
+    position: 'bottom-right',
+    theme: 'light'
+  };
+
+  authConfig: AiAuthConfig = {
+    jwtToken: 'your-jwt-token-here'
+  };
+}
+```
+
+### Option 2: Standalone Component (Angular 19+)
+
+```typescript
+import { bootstrapApplication } from '@angular/platform-browser';
+import { AppComponent } from './app.component';
+
+bootstrapApplication(AppComponent);
+```
+
+```typescript
+import { Component } from '@angular/core';
+import { AiChatWidgetComponent, AiWidgetConfig } from '@courseecho/ai-widget-angular';
+
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  imports: [AiChatWidgetComponent],
+  template: `
+    <app-ai-chat-widget [config]="config"></app-ai-chat-widget>
+  `
+})
+export class AppComponent {
+  config: AiWidgetConfig = {
+    apiEndpoint: 'http://localhost:5000',
+    position: 'bottom-right'
+  };
+}
+```
+
+## 🎯 Configuration
+
+### Basic Configuration
+
+```typescript
+import { AiWidgetConfig, AiAuthConfig } from '@courseecho/ai-widget-angular';
+
+const config: AiWidgetConfig = {
+  // Required
+  apiEndpoint: 'http://localhost:5000',
+
+  // Optional
+  enableFloatingButton: true,
+  position: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left',
+  theme: 'light' | 'dark',
+  
+  // Context tracking
+  contextConfig: {
+    enableContextTracking: true,
+    contextUpdateInterval: 5000,
+    includePageMetadata: true
+  }
+};
+
+const authConfig: AiAuthConfig = {
+  jwtToken: 'your-jwt-token', // Option 1
+  // OR
+  apiKey: 'your-api-key',     // Option 2
+  // OR
+  refreshTokenFn: async () => {
+    // Fetch new token from your auth service
+    return 'new-jwt-token';
+  }
+};
+```
+
+## 🔧 Service Usage
+
+Inject `AiWidgetService` to use the SDK directly:
+
+```typescript
+import { Component, OnInit } from '@angular/core';
+import { AiWidgetService } from '@courseecho/ai-widget-angular';
+
+@Component({
+  selector: 'app-chat-page',
+  template: `
+    <div class="chat-container">
+      <div *ngFor="let msg of (messages$ | async)" class="message">
+        {{ msg.content }}
+      </div>
+      <input [(ngModel)]="userInput" />
+      <button (click)="send()">Send</button>
+    </div>
+  `
+})
+export class ChatPageComponent implements OnInit {
+  messages$ = this.aiService.messages$;
+  loading$ = this.aiService.loading$;
+  error$ = this.aiService.error$;
+
+  userInput = '';
+
+  constructor(private aiService: AiWidgetService) {}
+
+  ngOnInit() {
+    this.aiService.initialize({
+      apiEndpoint: 'http://localhost:5000',
+      contextConfig: { enableContextTracking: true }
+    }, {
+      jwtToken: 'your-token'
+    });
+  }
+
+  async send() {
+    try {
+      await this.aiService.sendQuery(this.userInput);
+      this.userInput = '';
+    } catch (error) {
+      console.error('Error:', error);
+    }
+  }
+
+  clearChat() {
+    this.aiService.clear();
+  }
+
+  exportChat() {
+    const data = this.aiService.exportChats('json');
+    const blob = new Blob([data], { type: 'application/json' });
+    const url = URL.createObjectURL(blob);
+    const link = document.createElement('a');
+    link.href = url;
+    link.download = `chat-${Date.now()}.json`;
+    link.click();
+  }
+}
+```
+
+## 📡 Service Methods
+
+### sendQuery(question: string)
+Send a question to the AI backend.
+
+```typescript
+try {
+  const response = await this.aiService.sendQuery('What is Angular?');
+  console.log('Response:', response);
+} catch (error) {
+  console.error('Error:', error);
+}
+```
+
+### setContext(context: AiContext)
+Set or update the page context.
+
+```typescript
+this.aiService.setContext({
+  pageUrl: window.location.href,
+  pageTitle: document.title,
+  userId: '123',
+  customData: { tier: 'premium' }
+});
+```
+
+### setJwt(token: string)
+Update JWT token.
+
+```typescript
+this.aiService.setJwt('new-token');
+```
+
+### setApiKey(key: string)
+Update API key.
+
+```typescript
+this.aiService.setApiKey('new-api-key');
+```
+
+### clear()
+Clear all messages and reset state.
+
+```typescript
+this.aiService.clear();
+```
+
+### exportChats(format: 'json' | 'csv')
+Export chat history.
+
+```typescript
+const json = this.aiService.exportChats('json');
+const csv = this.aiService.exportChats('csv');
+```
+
+### checkHealth()
+Check backend API health.
+
+```typescript
+try {
+  await this.aiService.checkHealth();
+  console.log('Backend is healthy');
+} catch (error) {
+  console.error('Backend is down');
+}
+```
+
+### getMessages()
+Get current messages (snapshot).
+
+```typescript
+const messages = this.aiService.getMessages();
+```
+
+### isLoading()
+Get loading state (snapshot).
+
+```typescript
+if (this.aiService.isLoading()) {
+  console.log('Loading...');
+}
+```
+
+### getError()
+Get current error (snapshot).
+
+```typescript
+const error = this.aiService.getError();
+if (error) {
+  console.error(error);
+}
+```
+
+## 📊 Reactive State Observables
+
+All state is available as RxJS observables:
+
+```typescript
+// Messages observable
+this.aiService.messages$.subscribe(messages => {
+  console.log('Messages:', messages);
+});
+
+// Loading state observable
+this.aiService.loading$.subscribe(isLoading => {
+  console.log('Is loading:', isLoading);
+});
+
+// Error observable
+this.aiService.error$.subscribe(error => {
+  if (error) console.error('Error:', error);
+});
+
+// Current context observable
+this.aiService.context$.subscribe(context => {
+  console.log('Context:', context);
+});
+
+// Charts observable
+this.aiService.charts$.subscribe(charts => {
+  console.log('Charts:', charts);
+});
+```
+
+Use with `async` pipe in templates:
+
+```html
+<div *ngFor="let chart of (charts$ | async)">
+  <!-- Render chart -->
+</div>
+```
+
+## 🎨 Component Customization
+
+### Position Options
+
+```typescript
+config: AiWidgetConfig = {
+  apiEndpoint: 'http://localhost:5000',
+  position: 'bottom-right' // 'bottom-left' | 'top-right' | 'top-left'
+};
+```
+
+### Theme Options
+
+```typescript
+config: AiWidgetConfig = {
+  apiEndpoint: 'http://localhost:5000',
+  theme: 'light' // 'light' | 'dark'
+};
+```
+
+### Custom Styling
+
+The component uses CSS custom properties for styling:
+
+```css
+.ai-widget-container {
+  --ai-primary: #3b82f6;
+  --ai-text: #1f2937;
+  --ai-bg: #ffffff;
+  --ai-border: #e5e7eb;
+  --ai-user-bg: #3b82f6;
+  --ai-assistant-bg: #f3f4f6;
+}
+
+.ai-widget-container.dark-theme {
+  --ai-primary: #2563eb;
+  --ai-text: #f3f4f6;
+  --ai-bg: #1f2937;
+  --ai-border: #374151;
+}
+```
+
+## 🔐 Authentication
+
+### JWT Token
+
+```typescript
+authConfig: AiAuthConfig = {
+  jwtToken: 'eyJhbGciOiJIUzI1NiIs...'
+};
+
+// Update token later
+this.aiService.setJwt('new-token');
+```
+
+### API Key
+
+```typescript
+authConfig: AiAuthConfig = {
+  apiKey: 'sk-prod-xxxxx'
+};
+
+// Update key later
+this.aiService.setApiKey('sk-prod-yyyyy');
+```
+
+### Token Refresh
+
+```typescript
+authConfig: AiAuthConfig = {
+  refreshTokenFn: async () => {
+    const response = await fetch('/api/refresh-token', {
+      method: 'POST'
+    });
+    const { token } = await response.json();
+    return token;
+  }
+};
+```
+
+## 🧪 Testing
+
+### Unit Tests
+
+```typescript
+import { TestBed } from '@angular/core/testing';
+import { AiWidgetService } from '@courseecho/ai-widget-angular';
+
+describe('AiWidgetService', () => {
+  let service: AiWidgetService;
+
+  beforeEach(() => {
+    TestBed.configureTestingModule({});
+    service = TestBed.inject(AiWidgetService);
+  });
+
+  it('should initialize', () => {
+    service.initialize({
+      apiEndpoint: 'http://localhost:5000'
+    });
+    expect(service).toBeDefined();
+  });
+
+  it('should send query', async () => {
+    service.initialize({
+      apiEndpoint: 'http://localhost:5000'
+    }, { jwtToken: 'test' });
+
+    const response = await service.sendQuery('Test question');
+    expect(response).toBeDefined();
+  });
+});
+```
+
+## ⚡ Performance Tips
+
+1. **Lazy load the widget**
+   ```typescript
+   loadWidget() {
+     this.showWidget = true;
+     this.aiService.initialize(config);
+   }
+   ```
+
+2. **Use OnPush change detection**
+   ```typescript
+   @Component({
+     changeDetection: ChangeDetectionStrategy.OnPush
+   })
+   ```
+
+3. **Unsubscribe properly**
+   ```typescript
+   private destroy$ = new Subject<void>();
+
+   ngOnInit() {
+     this.aiService.messages$
+       .pipe(takeUntil(this.destroy$))
+       .subscribe(...);
+   }
+
+   ngOnDestroy() {
+     this.destroy$.next();
+     this.destroy$.complete();
+   }
+   ```
+
+## 🐛 Error Handling
+
+```typescript
+async sendQuery(question: string) {
+  try {
+    const response = await this.aiService.sendQuery(question);
+    console.log('Success:', response);
+  } catch (error) {
+    if (error instanceof Error) {
+      if (error.message.includes('401')) {
+        console.error('Unauthorized - check your token');
+      } else if (error.message.includes('404')) {
+        console.error('API endpoint not found');
+      } else {
+        console.error('Unknown error:', error.message);
+      }
+    }
+  }
+}
+
+// Subscribe to error observable
+this.aiService.error$.subscribe(error => {
+  if (error) {
+    // Show error toast/snackbar
+    this.snackBar.open(error, 'Close');
+  }
+});
+```
+
+## 📚 Comparison with Other Frameworks
+
+| Feature | Angular 19+ | React | Vue 3 |
+|---------|-------------|-------|-------|
+| Component | Standalone | Functional | Composition |
+| State | RxJS Observables | Hooks | Composables |
+| Bundle Size | 18KB | 15KB | 12KB |
+| Modern Syntax | @if, @for, @switch | JSX | Template |
+| Performance | Excellent | Excellent | Excellent |
+| Type Safety | Excellent | Good | Good |
+
+## 🚀 Deployment
+
+### Build for Production
+
+```bash
+npm run build
+```
+
+### Include in Angular Build
+
+The package is automatically bundled with your Angular app.
+
+### Self-Hosted Package
+
+```bash
+npm install
+npm run build
+# Output in dist/ folder
+```
+
+## 🔗 Resources
+
+- [Integration Guide](../MULTI_FRAMEWORK_INTEGRATION_GUIDE.md#angular-integration)
+- [Quick Start](../QUICK_START_CHEATSHEET.md#angular)
+- [API Reference](../CAPABILITIES_AND_ENDPOINTS.md)
+- [Product Overview](../PRODUCT_OVERVIEW.md)
+
+## 📝 Types
+
+```typescript
+interface AiMessage {
+  id: string;
+  role: 'user' | 'assistant';
+  content: string;
+  timestamp: Date;
+  sources?: string[];
+  isStreaming?: boolean;
+}
+
+interface AiResponse {
+  success: boolean;
+  answer: string;
+  sources?: string[];
+  charts?: AiChart[];
+  followUpQuestions?: string[];
+  error?: string;
+}
+
+interface AiContext {
+  pageUrl: string;
+  pageTitle: string;
+  userId?: string;
+  sessionId?: string;
+  customData?: Record<string, any>;
+}
+
+interface AiWidgetConfig {
+  apiEndpoint: string;
+  enableFloatingButton?: boolean;
+  position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+  theme?: 'light' | 'dark';
+  contextConfig?: AiContextConfig;
+}
+
+interface AiAuthConfig {
+  jwtToken?: string;
+  apiKey?: string;
+  refreshTokenFn?: () => Promise<string>;
+}
+```
+
+## 🆘 Troubleshooting
+
+**Q: Widget doesn't appear**
+- Ensure backend API is running
+- Check API endpoint configuration
+- Verify CORS is enabled on backend
+
+**Q: Authentication fails**
+- Verify JWT token is valid
+- Check token hasn't expired
+- Ensure API supports the auth method
+
+**Q: Performance issues**
+- Check network in DevTools
+- Verify backend latency
+- Use OnPush change detection
+
+## 📞 Support
+
+- See [README.md](../README.md) for all resources
+- Check [QUICK_START_CHEATSHEET.md](../QUICK_START_CHEATSHEET.md) for common issues
+- Review [CAPABILITIES_AND_ENDPOINTS.md](../CAPABILITIES_AND_ENDPOINTS.md) for API details
+
+## 📄 License
+
+MIT - Free to use, modify, and distribute
+
+---
+
+**Ready to get started?** Install the package and follow the Quick Start above!
+