@aslaluroba/help-center 3.1.0 → 4.0.1

package/README.md

@@ -5,72 +5,52 @@ A powerful and customizable help center widget for Angular applications with rea
 ## Installation
 
 ```bash
+yarn add @aslaluroba/help-center
 npm install @aslaluroba/help-center
 ```
 
 ## Setup and Configuration
 
-1. Import and configure the widget in your app.module.ts:
+1. Provide `ApiService` once (e.g., in `main.ts`) and use the standalone component in your app:
 
 ```typescript
-import { HelpCenterWidgetComponent, ApiService } from '@aslaluroba/help-center'
+import { bootstrapApplication } from "@angular/platform-browser";
+import { Component, OnInit, inject } from "@angular/core";
+import { ApiService, ApiConfig, Language, HelpCenterWidgetComponent } from "@aslaluroba/help-center";
 
-@NgModule({
-  imports: [HelpCenterWidgetComponent],
-  providers: [ApiService]
-})
-export class AppModule {}
-```
-
-2. Initialize and use the widget in your component:
-
-```typescript
-import { Component, OnInit } from '@angular/core'
-import { ApiService, ApiConfig, Language } from '@aslaluroba/help-center'
+bootstrapApplication(AppComponent, {
+  providers: [ApiService],
+});
 
 @Component({
-  selector: 'app-root',
-  template: `
-    <app-help-center-widget 
-      [getToken]="getToken"
-      [helpScreenId]="helpScreenId" 
-      [currentLang]="currentLang" 
-      [showArrow]="true"
-      [primaryColor]="primaryColor"
-      [logoUrl]="logoUrl">
-    </app-help-center-widget>
-  `
+  selector: "app-root",
+  standalone: true,
+  imports: [HelpCenterWidgetComponent],
+  template: ` <app-help-center-widget [getToken]="getToken" [helpScreenId]="helpScreenId" [currentLang]="currentLang" [showArrow]="true" [primaryColor]="primaryColor" [logoUrl]="logoUrl"> </app-help-center-widget> `,
 })
 export class AppComponent implements OnInit {
-  helpScreenId = 'your-help-screen-id' // Required: Your unique help screen ID
-  currentLang: Language = 'en' // Default language
-  primaryColor = '#ad49e1' // Optional: Custom primary color (default: purple)
-  logoUrl = 'assets/logo.svg' // Optional: Custom logo URL (default: built-in logo)
+  private apiService = inject(ApiService);
 
-  constructor(private apiService: ApiService) {}
+  helpScreenId = "your-help-screen-id";
+  currentLang: Language = "en";
+  primaryColor = "#ad49e1";
+  logoUrl = "assets/logo.svg";
 
   ngOnInit() {
-    // Initialize API with authentication
     const apiConfig: ApiConfig = {
-      getToken: async () => {
-        // Implement your token retrieval logic
-        const response = await fetch('your-auth-endpoint')
-        const data = await response.json()
-        return data.token
-      }
-      // Optional: Override default API URL (default: 'https://babylai.net/api')
+      getToken: this.getToken,
+      // Optional: baseUrl override (default: https://babylai.net/api)
       // baseUrl: 'https://your-custom-api.com'
-    }
+    };
 
-    this.apiService.initialize(apiConfig)
+    this.apiService.initialize(apiConfig);
   }
 
   getToken = async () => {
-    // Your token retrieval implementation
-    const response = await fetch('your-auth-endpoint')
-    const data = await response.json()
-    return data.token
-  }
+    const response = await fetch("your-auth-endpoint");
+    const data = await response.json();
+    return data.token;
+  };
 }
 ```
 
@@ -79,6 +59,7 @@ export class AppComponent implements OnInit {
 The widget includes a comprehensive user feedback system that collects ratings and comments after meaningful chat interactions:
 
 ### Review Dialog Features
+
 - **Star Rating**: 1-5 star rating system with visual feedback
 - **Comment Collection**: Text area for detailed feedback (10-500 characters)
 - **Smart Display**: Only appears after meaningful chat interactions (not just welcome messages)
@@ -87,6 +68,7 @@ The widget includes a comprehensive user feedback system that collects ratings a
 - **Multi-language**: Fully translated interface
 
 ### Review API Endpoint
+
 Reviews are submitted to: `POST /Client/ClientChatSession/{sessionId}/review`
 
 ```typescript
@@ -98,6 +80,7 @@ Reviews are submitted to: `POST /Client/ClientChatSession/{sessionId}/review`
 ```
 
 ### Review Dialog Behavior
+
 - **Triggers**: Only after ending a chat with meaningful interaction
 - **Skips**: If user just opens chat without interaction
 - **Validation**: Client-side validation with real-time feedback
@@ -109,20 +92,29 @@ Reviews are submitted to: `POST /Client/ClientChatSession/{sessionId}/review`
 The widget includes intelligent chat session management to provide a seamless user experience:
 
 ### Confirmation Dialogs
+
 - **End Chat Confirmation**: Prevents accidental loss of active conversations
 - **Start New Chat Confirmation**: Warns users when switching between chat sessions
 - **Smart Detection**: Distinguishes between welcome messages and meaningful interactions
 
 ### Session Persistence
+
 - **Back Navigation**: Chat state maintained when navigating back to help screen
 - **Return to Chat**: Users can return to their previous conversation
 - **Duplicate Prevention**: Intelligent message handling prevents duplicate welcome messages
 
 ### Session States
+
 - **Active Session**: User has meaningful interaction (not just welcome message)
 - **Welcome Only**: User opened chat but didn't interact meaningfully
 - **Clean State**: No previous session or messages
 
+### Attachments
+
+- Users can add files; uploads are presigned and stored via S3
+- Pending files are uploaded after the first message creates a session
+- Attachment IDs are sent with messages and delivered in Ably payloads
+
 ## Language Support
 
 The widget supports multiple languages with built-in RTL support. Currently available languages:
@@ -135,11 +127,11 @@ The widget supports multiple languages with built-in RTL support. Currently avai
 1. Simple language switch:
 
 ```typescript
-import { Component } from '@angular/core'
-import { Language } from '@aslaluroba/help-center'
+import { Component } from "@angular/core";
+import { Language } from "@aslaluroba/help-center";
 
 @Component({
-  selector: 'app-root',
+  selector: "app-root",
   template: `
     <div>
       <!-- Language Switcher -->
@@ -149,47 +141,41 @@ import { Language } from '@aslaluroba/help-center'
       </div>
 
       <!-- Widget -->
-      <app-help-center-widget 
-        [getToken]="getToken"
-        [helpScreenId]="helpScreenId" 
-        [currentLang]="currentLang"
-        [primaryColor]="primaryColor"
-        [logoUrl]="logoUrl">
-      </app-help-center-widget>
+      <app-help-center-widget [getToken]="getToken" [helpScreenId]="helpScreenId" [currentLang]="currentLang" [primaryColor]="primaryColor" [logoUrl]="logoUrl"> </app-help-center-widget>
     </div>
-  `
+  `,
 })
 export class AppComponent {
-  helpScreenId = 'your-help-screen-id'
-  currentLang: Language = 'en'
-  primaryColor = '#ad49e1'
-  logoUrl = 'assets/logo.svg'
+  helpScreenId = "your-help-screen-id";
+  currentLang: Language = "en";
+  primaryColor = "#ad49e1";
+  logoUrl = "assets/logo.svg";
 
   getToken = async () => {
     // Your token implementation
-    return 'your-token'
-  }
+    return "your-token";
+  };
 }
 ```
 
 2. Using Translation Service (for advanced usage):
 
 ```typescript
-import { Component } from '@angular/core'
-import { TranslationService, Language } from '@aslaluroba/help-center'
+import { Component } from "@angular/core";
+import { TranslationService, Language } from "@aslaluroba/help-center";
 
 @Component({
-  selector: 'app-root'
+  selector: "app-root",
 })
 export class AppComponent {
   constructor(private translationService: TranslationService) {
     // Subscribe to language changes
     this.translationService.currentLang.subscribe((lang: Language) => {
-      console.log('Current language:', lang)
-    })
+      console.log("Current language:", lang);
+    });
 
     // Change language
-    this.translationService.setLanguage('ar')
+    this.translationService.setLanguage("ar");
   }
 }
 ```
@@ -205,15 +191,16 @@ The `primaryColor` property allows you to customize the color scheme throughout
 ```typescript
 // Example usage
 export class AppComponent {
-  primaryColor = '#3b82f6' // Blue theme
+  primaryColor = "#3b82f6"; // Blue theme
   // or
-  primaryColor = '#10b981' // Green theme
+  primaryColor = "#10b981"; // Green theme
   // or
-  primaryColor = '#ff6b35' // Orange theme
+  primaryColor = "#ff6b35"; // Orange theme
 }
 ```
 
 **Supported Color Formats:**
+
 - Hex colors: `#3b82f6`, `#10b981`
 - RGB: `rgb(59, 130, 246)`
 - HSL: `hsl(217, 91%, 60%)`
@@ -228,15 +215,16 @@ The `logoUrl` property allows you to display your custom logo in the help button
 ```typescript
 // Example usage
 export class AppComponent {
-  logoUrl = '/assets/my-logo.png' // Local asset
+  logoUrl = "/assets/my-logo.png"; // Local asset
   // or
-  logoUrl = 'https://example.com/logo.png' // External URL
+  logoUrl = "https://example.com/logo.png"; // External URL
   // or
-  logoUrl = 'assets/logo.svg' // Default logo (fallback)
+  logoUrl = "assets/logo.svg"; // Default logo (fallback)
 }
 ```
 
 **Logo Requirements:**
+
 - **Format**: PNG, JPG, SVG, or any web-compatible image format
 - **Size**: Recommended 50x50px for optimal display
 - **Fallback**: If the provided logo fails to load, it will fallback to the default logo
@@ -244,41 +232,32 @@ export class AppComponent {
 ### Complete Theming Example
 
 ```typescript
-import { Component } from '@angular/core'
+import { Component } from "@angular/core";
 
 @Component({
-  selector: 'app-root',
-  template: `
-    <app-help-center-widget 
-      [getToken]="getToken"
-      [helpScreenId]="helpScreenId"
-      [primaryColor]="primaryColor"
-      [logoUrl]="logoUrl"
-      [currentLang]="currentLang"
-      [showArrow]="true">
-    </app-help-center-widget>
-  `
+  selector: "app-root",
+  template: ` <app-help-center-widget [getToken]="getToken" [helpScreenId]="helpScreenId" [primaryColor]="primaryColor" [logoUrl]="logoUrl" [currentLang]="currentLang" [showArrow]="true"> </app-help-center-widget> `,
 })
 export class AppComponent {
-  helpScreenId = 'your-help-screen-id'
-  currentLang = 'en'
-  primaryColor = '#3b82f6' // Blue theme
-  logoUrl = '/assets/company-logo.png'
+  helpScreenId = "your-help-screen-id";
+  currentLang = "en";
+  primaryColor = "#3b82f6"; // Blue theme
+  logoUrl = "/assets/company-logo.png";
 
   getToken = async () => {
     // Your token implementation
-    return 'your-token'
-  }
+    return "your-token";
+  };
 
   // Dynamic theme switching
   switchToGreenTheme() {
-    this.primaryColor = '#10b981'
-    this.logoUrl = '/assets/green-logo.png'
+    this.primaryColor = "#10b981";
+    this.logoUrl = "/assets/green-logo.png";
   }
 
   switchToPurpleTheme() {
-    this.primaryColor = '#ad49e1'
-    this.logoUrl = '/assets/purple-logo.png'
+    this.primaryColor = "#ad49e1";
+    this.logoUrl = "/assets/purple-logo.png";
   }
 }
 ```
@@ -293,52 +272,38 @@ export class AppComponent {
 - **Customizable Theming**: Dynamic color schemes and logo customization
 - **Responsive Design**: Mobile-first approach with accessibility features
 - **Duplicate Prevention**: Smart message handling to prevent duplicate content
+- **File Attachments**: Presigned uploads with attachment IDs delivered to the assistant
 
 ## Props
 
-| Prop                | Type     | Required | Default      | Description                                      |
-| ------------------- | -------- | -------- | ------------ | ------------------------------------------------ |
-| getToken            | function | Yes      | -            | Function that returns a Promise<string> for auth |
-| helpScreenId        | string   | Yes      | -            | Unique help screen identifier                    |
-| currentLang         | Language | No       | 'en'         | UI language ('en' \| 'ar')                       |
-| showArrow           | boolean  | No       | true         | Show/hide floating arrow                         |
-| messageLabel        | string   | No       | null         | Custom message for the help button               |
-| isIntroScreenEnabled| boolean  | No       | false        | Enable/disable intro screen                      |
-| primaryColor        | string   | No       | '#ad49e1'    | Primary color for theming (hex format)           |
-| logoUrl             | string   | No       | '/logo.svg' | URL path to custom logo image                    |
+| Prop                 | Type     | Required | Default     | Description                                      |
+| -------------------- | -------- | -------- | ----------- | ------------------------------------------------ |
+| getToken             | function | Yes      | -           | Function that returns a Promise<string> for auth |
+| helpScreenId         | string   | Yes      | -           | Unique help screen identifier                    |
+| currentLang          | Language | No       | 'en'        | UI language ('en' \| 'ar')                       |
+| showArrow            | boolean  | No       | true        | Show/hide floating arrow                         |
+| messageLabel         | string   | No       | null        | Custom message for the help button               |
+| primaryColor         | string   | No       | '#ad49e1'   | Primary color for theming (hex format)           |
+| logoUrl              | string   | No       | '/logo.svg' | URL path to custom logo image                    |
 
 ## Quick Reference
 
 ### Basic Usage
+
 ```html
-<app-help-center-widget 
-  [getToken]="getToken"
-  [helpScreenId]="helpScreenId">
-</app-help-center-widget>
+<app-help-center-widget [getToken]="getToken" [helpScreenId]="helpScreenId"> </app-help-center-widget>
 ```
 
 ### With Custom Theme
+
 ```html
-<app-help-center-widget 
-  [getToken]="getToken"
-  [helpScreenId]="helpScreenId"
-  [primaryColor]="'#3b82f6'"
-  [logoUrl]="'/my-logo.png'">
-</app-help-center-widget>
+<app-help-center-widget [getToken]="getToken" [helpScreenId]="helpScreenId" [primaryColor]="'#3b82f6'" [logoUrl]="'/my-logo.png'"> </app-help-center-widget>
 ```
 
 ### With All Options
+
 ```html
-<app-help-center-widget 
-  [getToken]="getToken"
-  [helpScreenId]="helpScreenId"
-  [currentLang]="'en'"
-  [showArrow]="true"
-  [messageLabel]="'Need help?'"
-  [isIntroScreenEnabled]="true"
-  [primaryColor]="'#3b82f6'"
-  [logoUrl]="'/my-logo.png'">
-</app-help-center-widget>
+<app-help-center-widget [getToken]="getToken" [helpScreenId]="helpScreenId" [currentLang]="'en'" [showArrow]="true" [messageLabel]="'Need help?'" [primaryColor]="'#3b82f6'" [logoUrl]="'/my-logo.png'"> </app-help-center-widget>
 ```
 
 ## Troubleshooting
@@ -346,16 +311,19 @@ export class AppComponent {
 ### Common Issues
 
 1. **Duplicate Welcome Messages**
+
    - **Fixed**: The widget now intelligently detects and prevents duplicate welcome messages
    - **Cause**: Previously occurred when starting new chat after going back
    - **Solution**: Smart session detection and proper session clearing
 
 2. **Review Dialog Not Showing**
+
    - **Expected**: Review dialog only appears after meaningful chat interactions
    - **Not Showing**: If user only sees welcome message without interaction
    - **Solution**: This is intentional behavior to avoid unnecessary review prompts
 
 3. **Chat Session Issues**
+
    - **Session Persistence**: Chat state is maintained when navigating back
    - **Confirmation Dialogs**: Prevent accidental loss of conversations
    - **Smart Detection**: System distinguishes between welcome messages and real interactions