@aslaluroba/help-center 3.1.0 → 4.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aslaluroba/help-center",
-  "version": "3.1.0",
+  "version": "4.0.1",
   "private": false,
   "license": "MIT",
   "peerDependencies": {
@@ -13,9 +13,13 @@
     "zone.js": ">=0.15.0"
   },
   "dependencies": {
-    "ably": "^2.14.0",
+    "@iconify-json/solar": "^1.2.5",
+    "@tailwindcss/postcss": "^4.1.18",
+    "ably": "^2.17.0",
     "clsx": "^2.1.1",
-    "marked": "^16.4.1",
+    "iconify-icon": "^3.0.2",
+    "marked": "^17.0.1",
+    "postcss": "^8.5.6",
     "prismjs": "^1.30.0",
     "tslib": "^2.8.1"
   },
@@ -43,13 +47,13 @@
   },
   "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e",
   "module": "fesm2022/aslaluroba-help-center.mjs",
-  "typings": "index.d.ts",
+  "typings": "types/aslaluroba-help-center.d.ts",
   "exports": {
     "./package.json": {
       "default": "./package.json"
     },
     ".": {
-      "types": "./index.d.ts",
+      "types": "./types/aslaluroba-help-center.d.ts",
       "default": "./fesm2022/aslaluroba-help-center.mjs"
     }
   }

package/types/aslaluroba-help-center.d.ts

@@ -0,0 +1,604 @@
+import * as _angular_core from '@angular/core';
+import { OnInit, OnDestroy, ElementRef, PipeTransform } from '@angular/core';
+import { Observable } from 'rxjs';
+
+type Language = 'en' | 'ar';
+interface TokenResponse {
+    token: string;
+    expiresIn: number;
+}
+interface Option {
+    id: string;
+    helpScreenId: string;
+    parentOptionId: string | null;
+    nestedOptions: Option[];
+    title: string;
+    paragraphs: string[];
+    chatWithUs: boolean;
+    assistantId?: string;
+    assistant?: {
+        id: string;
+        tenantId: string;
+        tenant: {
+            id: string;
+            name: string;
+            key: string;
+        };
+        name: string;
+        openAIAssistantId: string;
+        greeting: string;
+        closing: string;
+    };
+    hasNestedOptions: boolean;
+    order: number;
+    icon?: string;
+}
+interface Message {
+    id: string | number;
+    sender: 'user' | 'assistant' | 'agent';
+    senderType: number;
+    messageContent: string;
+    sentAt: Date;
+    isSeen: boolean;
+    attachmentIds?: string[];
+    isReviewMessage?: boolean;
+}
+interface Tenant {
+    id: string;
+    name: string;
+    key: string;
+    logoUrl?: string | null;
+    autoCloseSessions?: boolean;
+    autoCloseSessionsAfter?: number;
+    settings?: {
+        description?: string;
+        theme?: {
+            primaryColor?: string;
+            secondaryColor?: string;
+        };
+    };
+}
+interface Assistant {
+    id: string;
+    tenantId: string;
+    tenant: Tenant;
+    name: string;
+    openAIAssistantId: string;
+    greeting: string;
+    closing: string;
+}
+interface HelpScreenFile {
+    id: string;
+    name: string;
+    url: string;
+    type: string;
+    size?: number;
+}
+interface HelpScreenOption {
+    id: string;
+    helpScreenId: string;
+    parentOptionId: string | null;
+    nestedOptions: HelpScreenOption[];
+    title: string;
+    paragraphs: string[];
+    files: HelpScreenFile[];
+    chatWithUs: boolean;
+    assistantId?: string;
+    assistant?: Assistant;
+    hasNestedOptions: boolean;
+    order: number;
+    icon?: string;
+}
+interface HelpScreenData {
+    id: string;
+    tenantId: string;
+    tenant: Tenant;
+    title: string;
+    description: string;
+    options: HelpScreenOption[];
+    chatWithUs: boolean;
+}
+interface PresignUploadRequestDto {
+    name: string;
+    contentType: string;
+    sizeBytes: number;
+    pathData: {
+        type: number;
+        chatSessionId: string;
+    };
+}
+interface PresignUploadResponse {
+    id: string;
+    uploadUrl: string;
+    path: string;
+    expiresAt: string;
+}
+interface PresignDownloadResponse {
+    id: string;
+    name: string;
+    downloadUrl: string;
+    contentType: string;
+    expiresAt: string;
+}
+interface SelectedFileDto {
+    file: File;
+    previewUrl: string;
+    uploading: boolean;
+    uploadedId: string | null;
+    error: string | null;
+}
+interface UploadResult {
+    fileId: string;
+    success: boolean;
+    error?: string;
+}
+
+declare class HelpCenterWidgetComponent implements OnInit, OnDestroy {
+    getToken: _angular_core.InputSignal<() => Promise<string>>;
+    helpScreenId: _angular_core.InputSignal<string>;
+    showArrow: _angular_core.InputSignal<boolean>;
+    messageLabel: _angular_core.InputSignal<string>;
+    currentLang: _angular_core.InputSignal<string>;
+    primaryColor: _angular_core.InputSignal<string>;
+    logoUrl: _angular_core.InputSignal<string>;
+    chatMessagesContainer: ElementRef;
+    isRTL: _angular_core.Signal<boolean>;
+    isPopupOpen: _angular_core.WritableSignal<boolean>;
+    helpScreenData: _angular_core.WritableSignal<HelpScreenData>;
+    status: _angular_core.WritableSignal<"idle" | "failed" | "loading" | "succeeded">;
+    error: _angular_core.WritableSignal<string>;
+    showArrowAnimation: _angular_core.WritableSignal<boolean>;
+    showTooltip: _angular_core.WritableSignal<boolean>;
+    sessionId: _angular_core.WritableSignal<string>;
+    isAblyConnected: _angular_core.WritableSignal<boolean>;
+    isChatClosed: _angular_core.WritableSignal<boolean>;
+    showChat: _angular_core.WritableSignal<boolean>;
+    messageText: _angular_core.WritableSignal<string>;
+    isTyping: _angular_core.WritableSignal<boolean>;
+    messages: _angular_core.WritableSignal<Message[]>;
+    showHelpScreenData: _angular_core.WritableSignal<boolean>;
+    chatIsLoading: _angular_core.WritableSignal<boolean>;
+    ablyToken: _angular_core.WritableSignal<string>;
+    needsAgent: _angular_core.WritableSignal<boolean>;
+    assistantStatus: _angular_core.WritableSignal<"typing" | "idle">;
+    selectedOption: _angular_core.WritableSignal<Option>;
+    selectedNestedOption: _angular_core.WritableSignal<Option>;
+    showEndChatConfirmation: _angular_core.WritableSignal<boolean>;
+    showStartNewChatConfirmation: _angular_core.WritableSignal<boolean>;
+    showReviewDialog: _angular_core.WritableSignal<boolean>;
+    isSubmittingReview: _angular_core.WritableSignal<boolean>;
+    isStartingNewChat: _angular_core.WritableSignal<boolean>;
+    pendingNewChatOption: _angular_core.WritableSignal<Option>;
+    hasUserSentMessages: _angular_core.WritableSignal<boolean>;
+    closedSessionIdForReview: _angular_core.WritableSignal<string>;
+    private apiService;
+    private translationService;
+    private themeService;
+    private chatSessionService;
+    private fileUploadService;
+    private destroyRef;
+    private themeEffectRef?;
+    private languageEffectRef?;
+    constructor();
+    ngOnInit(): void;
+    ngOnDestroy(): void;
+    handleTogglePopup(): Promise<void>;
+    private fetchHelpScreenData;
+    createChatSession(option?: Option): Promise<{
+        chatSession: {
+            id: string;
+        };
+        ablyToken: string;
+    }>;
+    sendMessage(event?: {
+        text: string;
+        attachmentIds: string[];
+        pendingFiles?: File[];
+    } | string): Promise<void>;
+    handleReceiveMessage(message: string | {
+        content: string;
+        attachments?: string[];
+    }, senderType: number, needsAgent: boolean): void;
+    private getSenderType;
+    private hasActiveChatSession;
+    private isWelcomeMessage;
+    handleStartNewChat(option: Option): Promise<void>;
+    private startNewChatSession;
+    handleStartChat(option: Option): Promise<void>;
+    handleEndChat(): Promise<void>;
+    confirmEndChat(): Promise<void>;
+    handleReviewSubmit(reviewData: {
+        rating: number;
+        comment: string;
+    }): Promise<void>;
+    handleReviewClose(): void;
+    handleReviewSkip(): Promise<void>;
+    private endChatSession;
+    private closeSessionOnly;
+    cancelEndChat(): void;
+    closeEndChat(): void;
+    confirmStartNewChat(): Promise<void>;
+    cancelStartNewChat(): void;
+    closeStartNewChat(): void;
+    private clearCurrentChat;
+    private startNewChatWithOption;
+    handleClosePopup(): Promise<void>;
+    handleMinimizePopup(): void;
+    handleCloseArrowAnimation(): void;
+    handleBack(): void;
+    handleShowChat(): void;
+    selectOption(option: Option): void;
+    selectNestedOption(nestedOption: Option): void;
+    handleShowHelpScreenData(): void;
+    private scrollTimeout?;
+    private scrollToBottom;
+    getDirection(): "ltr" | "rtl";
+    get helpScreenDataList(): {
+        icon: string;
+        title: string;
+        description: string;
+        actionLabel: string;
+        action: () => Promise<void>;
+    }[];
+    navigateToUrl(url: string): void;
+    private addReviewMessageToChat;
+    handleReviewSubmitFromChat(reviewData: {
+        rating: number;
+        comment: string;
+    }): Promise<void>;
+    handleReviewSkipFromChat(): Promise<void>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<HelpCenterWidgetComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<HelpCenterWidgetComponent, "app-help-center-widget", never, { "getToken": { "alias": "getToken"; "required": true; "isSignal": true; }; "helpScreenId": { "alias": "helpScreenId"; "required": true; "isSignal": true; }; "showArrow": { "alias": "showArrow"; "required": false; "isSignal": true; }; "messageLabel": { "alias": "messageLabel"; "required": false; "isSignal": true; }; "currentLang": { "alias": "currentLang"; "required": false; "isSignal": true; }; "primaryColor": { "alias": "primaryColor"; "required": false; "isSignal": true; }; "logoUrl": { "alias": "logoUrl"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+type GetTokenFn = () => Promise<string>;
+/**
+ * Service for managing help center configuration.
+ *
+ * Stores configuration such as API base URL and token retrieval function.
+ * This service is used internally by other services to access configuration.
+ *
+ * @publicApi
+ */
+declare class HelpCenterConfigService {
+    private _apiBaseUrl;
+    private _getTokenFn?;
+    setApiBaseUrl(url: string): void;
+    getApiBaseUrl(): string;
+    setGetTokenFn(fn: GetTokenFn): void;
+    getTokenFn(): GetTokenFn | undefined;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<HelpCenterConfigService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<HelpCenterConfigService>;
+}
+
+/**
+ * Service for handling API requests with automatic authentication token management.
+ *
+ * Features:
+ * - Automatic token refresh on expiry
+ * - Token validation and format checking
+ * - Secure token storage using sessionStorage
+ * - Endpoint validation to prevent SSRF attacks
+ *
+ * @publicApi
+ */
+declare class ApiService {
+    private getTokenFunction;
+    private baseUrl;
+    /**
+     * Initialize the API service with authentication configuration.
+     *
+     * This must be called before making any API requests. The service will use
+     * the provided token function to fetch and refresh tokens automatically.
+     *
+     * @param config Configuration object containing token function and optional base URL
+     * @throws Error if getToken function is not provided
+     *
+     * @example
+     * ```typescript
+     * apiService.initialize({
+     *   getToken: async () => {
+     *     const response = await fetch('/auth/token');
+     *     const data = await response.json();
+     *     return data.token;
+     *   },
+     *   baseUrl: 'https://api.example.com'
+     * });
+     * ```
+     */
+    initialize(config: ApiConfig): void;
+    /**
+     * Validate token format
+     * JWT tokens must have exactly 3 parts separated by dots (header.payload.signature)
+     */
+    private validateToken;
+    /**
+     * Retrieves a valid authentication token, fetching a new one if expired.
+     *
+     * Tokens are cached for 15 minutes. The service provides backward compatibility:
+     * - Checks localStorage first for existing tokens (backward compatibility)
+     * - Falls back to sessionStorage if no token found in localStorage
+     * - New tokens are stored in sessionStorage (preferred) or localStorage (fallback)
+     * - Automatically migrates tokens from localStorage to sessionStorage when found
+     *
+     * After expiry, a new token is automatically fetched using the configured getToken function.
+     *
+     * @param forceRefresh If true, forces a new token fetch even if current token is valid
+     * @returns Promise resolving to a valid authentication token
+     * @throws Error if API service is not initialized or token format is invalid
+     */
+    getValidToken(forceRefresh?: boolean): Promise<string>;
+    private fetchWithAuth;
+    /**
+     * Validate endpoint to prevent SSRF vulnerabilities
+     *
+     * Protects against:
+     * - Absolute URLs with any protocol (case-insensitive)
+     * - Protocol-relative URLs
+     * - Dangerous protocols (ftp, file, data, javascript, etc.)
+     * - URL-encoded path traversal
+     * - Double-encoded attacks
+     */
+    private validateEndpoint;
+    /**
+     * Makes an authenticated API request with automatic token management.
+     *
+     * This method automatically:
+     * - Validates the endpoint to prevent SSRF attacks
+     * - Adds authentication headers with a valid token
+     * - Retries with a fresh token if authentication fails
+     * - Handles errors and returns appropriate error messages
+     *
+     * @param endpoint API endpoint path (relative to baseUrl)
+     * @param method HTTP method (default: 'GET')
+     * @param body Request body object (will be JSON stringified)
+     * @param customHeaders Additional headers to include in the request
+     * @returns Promise resolving to the Response object
+     * @throws Error if endpoint validation fails, request fails, or authentication fails
+     *
+     * @example
+     * ```typescript
+     * // GET request
+     * const response = await apiService.apiRequest('client/help-screens/123');
+     * const data = await response.json();
+     *
+     * // POST request
+     * const response = await apiService.apiRequest(
+     *   'client/chat-sessions',
+     *   'POST',
+     *   { helpScreenId: '123' }
+     * );
+     * ```
+     */
+    apiRequest<T = unknown>(endpoint: string, method?: string, body?: T | null, customHeaders?: Record<string, string>): Promise<Response>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ApiService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<ApiService>;
+}
+
+/**
+ * Service for retrieving authentication tokens from the configured token function.
+ *
+ * This service acts as a wrapper around the configured token retrieval function,
+ * providing a consistent interface for token management.
+ *
+ * @publicApi
+ */
+declare class TokenService {
+    private config;
+    /**
+     * Retrieves an authentication token using the configured token function.
+     *
+     * @returns Promise resolving to a TokenResponse containing the token and expiry time
+     * @throws Error if no token function is configured
+     */
+    getToken(): Promise<TokenResponse>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<TokenService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<TokenService>;
+}
+
+type TranslationKey = 'ChatIntroMessage' | 'BabylaiTitle' | 'BabylaiDescription' | 'ChatNow' | 'TryBableAI' | 'ContactUs' | 'HelpCenter' | 'BabylAI' | 'ChatPlaceholder' | 'PoweredByBabylAI' | 'EndChat' | 'LeavingDialogTitle' | 'LeavingDialogBody' | 'StartNewChatDialogTitle' | 'StartNewChatDialogBody' | 'ReviewDialogTitle' | 'ReviewDialogDescription' | 'ReviewDialogRatingLabel' | 'ReviewDialogCommentLabel' | 'ReviewDialogCommentPlaceholder' | 'ReviewDialogSubmitButton' | 'ReviewDialogSkipButton' | 'Confirm' | 'Cancel' | 'Close' | 'Back' | 'title' | 'ErrorFetchingHelpScreen' | 'ErrorSendingMessage' | 'ErrorStartingChat' | 'ErrorEndingChat' | 'ErrorSubmittingReview' | 'ErrorClosingChat' | 'ErrorCreatingSession' | 'ErrorNetworkFailure' | 'ErrorUnknown' | 'ErrorMessageTooLong' | 'ErrorMessageEmpty' | 'CloseChat' | 'Continue';
+/**
+ * Service for managing translations and language switching.
+ *
+ * Supports multiple languages (currently English and Arabic) with RTL support.
+ * Provides reactive language changes through Observable pattern.
+ *
+ * @publicApi
+ */
+declare class TranslationService {
+    private translations;
+    private _currentLang;
+    readonly currentLang: Observable<Language>;
+    /**
+     * Translates a translation key to the current language.
+     *
+     * @param key Translation key to look up
+     * @returns Translated string in the current language, or the key itself if translation not found
+     *
+     * @example
+     * ```typescript
+     * const message = translationService.translate('ChatNow');
+     * // Returns 'Let\'s Chat' in English or 'دعنا نتحدث' in Arabic
+     * ```
+     */
+    translate(key: TranslationKey): string;
+    /**
+     * Sets the current language for translations.
+     *
+     * @param lang Language code ('en' or 'ar')
+     *
+     * @example
+     * ```typescript
+     * translationService.setLanguage('ar'); // Switch to Arabic
+     * ```
+     */
+    setLanguage(lang: Language): void;
+    /**
+     * Gets the current language code.
+     *
+     * @returns Current language code ('en' or 'ar')
+     */
+    getCurrentLang(): Language;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<TranslationService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<TranslationService>;
+}
+
+/**
+ * Service for managing chat session lifecycle and operations.
+ *
+ * Handles:
+ * - Chat session creation and management
+ * - Ably connection management
+ * - Message sending operations
+ *
+ * @publicApi
+ */
+declare class ChatSessionService {
+    private apiService;
+    /**
+     * Creates a new chat session with the specified option.
+     *
+     * @param option The help screen option to create a chat session for
+     * @param helpScreenId The help screen ID
+     * @param currentLang Current language code for API headers
+     * @returns Promise resolving to session data including sessionId and ablyToken
+     * @throws Error if session creation fails
+     */
+    createSession(option: Option, helpScreenId: string, currentLang: string): Promise<{
+        chatSession: {
+            id: string;
+        };
+        ablyToken: string;
+    }>;
+    /**
+     * Establishes Ably real-time connection for a chat session.
+     *
+     * @param sessionId The chat session ID
+     * @param ablyToken The Ably authentication token
+     * @param onMessageReceived Callback function for received messages
+     * @param tenantId The tenant ID for the connection
+     * @param option Optional option for token refresh (needed for token renewal)
+     * @param helpScreenId Optional help screen ID for token refresh
+     * @param currentLang Optional current language for token refresh
+     */
+    establishAblyConnection(sessionId: string, ablyToken: string, onMessageReceived: (message: string | {
+        content: string;
+        attachments?: string[];
+    }, senderType: number, needsAgent: boolean) => void, tenantId: string, option?: Option, helpScreenId?: string, currentLang?: string): Promise<void>;
+    /**
+     * Sends a message in an active chat session.
+     *
+     * @param sessionId The chat session ID
+     * @param messageContent The message content to send
+     * @param currentLang Current language code for API headers
+     * @throws Error if message sending fails
+     */
+    sendMessage(sessionId: string, messageContent: string, currentLang: string, attachmentIds?: string[]): Promise<void>;
+    /**
+     * Closes a chat session.
+     *
+     * @param sessionId The chat session ID to close
+     * @param currentLang Current language code for API headers
+     * @returns Promise resolving to the close response
+     * @throws Error if session closing fails
+     */
+    closeSession(sessionId: string, currentLang: string): Promise<unknown>;
+    /**
+     * Submits a review for a chat session.
+     *
+     * @param sessionId The chat session ID
+     * @param rating Rating value (1-5)
+     * @param comment Review comment (10-500 characters)
+     * @param currentLang Current language code for API headers
+     * @throws Error if review submission fails
+     */
+    submitReview(sessionId: string, rating: number, comment: string, currentLang: string): Promise<void>;
+    /**
+     * Stops the Ably connection.
+     */
+    stopConnection(): Promise<void>;
+    /**
+     * Checks if Ably connection is active.
+     *
+     * @returns True if connection is active, false otherwise
+     */
+    isConnectionActive(): boolean;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ChatSessionService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<ChatSessionService>;
+}
+
+/**
+ * Service for managing language switching.
+ *
+ * Provides a simplified interface for switching between supported languages.
+ * This service wraps TranslationService for easier language management.
+ *
+ * @publicApi
+ */
+declare class LanguageService {
+    private translationService;
+    /**
+     * Switches the application language.
+     *
+     * @param language Language code to switch to ('en' or 'ar')
+     *
+     * @example
+     * ```typescript
+     * languageService.switchLanguage('ar'); // Switch to Arabic
+     * ```
+     */
+    switchLanguage(language: Language): void;
+    /**
+     * Gets the current application language.
+     *
+     * @returns Current language code ('en' or 'ar')
+     */
+    getCurrentLang(): Language;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<LanguageService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<LanguageService>;
+}
+
+/**
+ * Angular pipe for translating keys in templates.
+ *
+ * Usage in templates:
+ * ```html
+ * {{ 'ChatNow' | translate }}
+ * ```
+ *
+ * @publicApi
+ */
+declare class TranslatePipe implements PipeTransform {
+    private translationService;
+    /**
+     * Transforms a translation key into the translated string for the current language.
+     *
+     * @param key Translation key to look up
+     * @returns Translated string in the current language
+     */
+    transform(key: TranslationKey): string;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<TranslatePipe, never>;
+    static ɵpipe: _angular_core.ɵɵPipeDeclaration<TranslatePipe, "translate", true>;
+}
+
+/**
+ * Configuration interface for API service initialization
+ *
+ * @publicApi
+ */
+interface ApiConfig {
+    /**
+     * Function that returns a promise resolving to an authentication token
+     * This function is called when tokens need to be refreshed
+     */
+    getToken: () => Promise<string>;
+    /**
+     * Optional base URL for API requests
+     * Defaults to 'https://babylai.net/api' if not provided
+     * Should use HTTPS in production environments
+     */
+    baseUrl?: string;
+}
+
+export { ApiService, ChatSessionService, HelpCenterConfigService, HelpCenterWidgetComponent, LanguageService, TokenService, TranslatePipe, TranslationService };
+export type { ApiConfig, Assistant, GetTokenFn, HelpScreenData, HelpScreenFile, HelpScreenOption, Language, Message, Option, PresignDownloadResponse, PresignUploadRequestDto, PresignUploadResponse, SelectedFileDto, Tenant, TokenResponse, TranslationKey, UploadResult };

package/index.d.ts

@@ -1,5 +0,0 @@
-/**
- * Generated bundle index. Do not edit.
- */
-/// <amd-module name="@aslaluroba/help-center" />
-export * from './public_api';

package/public_api.d.ts

@@ -1,12 +0,0 @@
-export * from './src/app/types';
-export interface ApiConfig {
-    getToken: () => Promise<string>;
-    baseUrl?: string;
-}
-export * from './src/app/help-center-widget/help-center-widget.component';
-export * from './src/app/services/help-center-config.service';
-export * from './src/app/services/api.service';
-export * from './src/app/services/token.service';
-export * from './src/app/services/translation.service';
-export * from './src/app/language.service';
-export * from './src/app/pipes/translate.pipe';