@weldsuite/helpdesk-widget-sdk 1.0.16 → 1.0.17

package/dist/react.d.ts

@@ -29,41 +29,6 @@ interface PositionConfig {
     left?: string;
     top?: string;
 }
-/**
- * Customization configuration
- */
-interface CustomizationConfig {
-    primaryColor?: string;
-    accentColor?: string;
-    backgroundColor?: string;
-    textColor?: string;
-    fontFamily?: string;
-    fontSize?: string;
-    borderRadius?: string;
-}
-/**
- * Feature flags
- */
-interface FeatureConfig {
-    attachments?: boolean;
-    reactions?: boolean;
-    typing?: boolean;
-    readReceipts?: boolean;
-    offlineMode?: boolean;
-    fileUpload?: boolean;
-    imageUpload?: boolean;
-    voiceMessages?: boolean;
-    videoMessages?: boolean;
-}
-/**
- * Mobile configuration
- */
-interface MobileConfig {
-    fullScreen?: boolean;
-    scrollLock?: boolean;
-    keyboardHandling?: 'auto' | 'manual';
-    safeAreaInsets?: boolean;
-}
 /**
  * Iframe configuration
  */
@@ -156,15 +121,13 @@ interface SecurityConfig {
  */
 interface WeldConfig {
     widgetId: string;
+    testMode?: boolean;
     api?: Partial<ApiConfig>;
     iframes?: Partial<IframeConfig>;
     position?: {
         launcher?: PositionConfig;
         widget?: PositionConfig;
     };
-    customization?: CustomizationConfig;
-    features?: FeatureConfig;
-    mobile?: MobileConfig;
     auth?: AuthConfig;
     locale?: LocaleConfig;
     logging?: LogConfig;
@@ -184,11 +147,9 @@ interface WeldConfig {
  */
 interface ResolvedConfig {
     widgetId: string;
+    testMode?: boolean;
     api: ApiConfig;
     iframes: IframeConfig;
-    customization: CustomizationConfig;
-    features: FeatureConfig;
-    mobile: MobileConfig;
     auth: AuthConfig;
     locale: LocaleConfig;
     logging: LogConfig;
@@ -458,6 +419,7 @@ declare class WeldSDK {
     private readyResolve;
     private boundHandleLauncherClick;
     private subscriptionIds;
+    private pageTrackingCleanup;
     constructor(config: WeldConfig);
     /**
      * Handle launcher click messages from iframe
@@ -491,6 +453,22 @@ declare class WeldSDK {
      * Check if SDK is ready
      */
     isReady(): boolean;
+    /**
+     * Update callbacks on an existing instance (used by singleton reuse)
+     */
+    updateCallbacks(config: Partial<WeldConfig>): void;
+    /**
+     * Persist open/closed state to sessionStorage
+     */
+    private persistOpenState;
+    /**
+     * Clear persisted state from sessionStorage
+     */
+    private clearPersistedState;
+    /**
+     * Check if widget was previously open (from sessionStorage)
+     */
+    private wasOpen;
     /**
      * Open the widget
      */
@@ -646,10 +624,23 @@ declare class WeldSDK {
      * Disable debug mode
      */
     disableDebug(): void;
+    /**
+     * Send a page change message to the widget iframe
+     */
+    private sendPageChange;
+    /**
+     * Start tracking page URL changes (SPA navigations + popstate)
+     */
+    private startPageTracking;
     /**
      * Ensure SDK is ready before operation
      */
     private ensureReady;
+    /**
+     * Detach from the current component lifecycle without destroying the widget.
+     * Use this as a React useEffect cleanup — the widget stays alive across navigations.
+     */
+    detach(): void;
     /**
      * Destroy SDK and cleanup
      */

package/dist/react.esm.js

@@ -33,32 +33,6 @@ const DEFAULT_CONFIG = {
             closeOnClick: true,
         },
     },
-    customization: {
-        primaryColor: '#000000',
-        accentColor: '#3b82f6',
-        backgroundColor: '#ffffff',
-        textColor: '#111827',
-        fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
-        fontSize: '14px',
-        borderRadius: '12px',
-    },
-    features: {
-        attachments: true,
-        reactions: true,
-        typing: true,
-        readReceipts: true,
-        offlineMode: false,
-        fileUpload: true,
-        imageUpload: true,
-        voiceMessages: false,
-        videoMessages: false,
-    },
-    mobile: {
-        fullScreen: true,
-        scrollLock: true,
-        keyboardHandling: 'auto',
-        safeAreaInsets: true,
-    },
     auth: {
         enabled: true,
         mode: 'anonymous',
@@ -102,6 +76,7 @@ function resolveConfig(config) {
     validateConfig(config);
     return {
         widgetId: config.widgetId,
+        testMode: config.testMode,
         api: {
             ...DEFAULT_CONFIG.api,
             widgetId: config.widgetId,
@@ -131,18 +106,6 @@ function resolveConfig(config) {
                 ...config.iframes?.backdrop,
             },
         },
-        customization: {
-            ...DEFAULT_CONFIG.customization,
-            ...config.customization,
-        },
-        features: {
-            ...DEFAULT_CONFIG.features,
-            ...config.features,
-        },
-        mobile: {
-            ...DEFAULT_CONFIG.mobile,
-            ...config.mobile,
-        },
         auth: {
             ...DEFAULT_CONFIG.auth,
             ...config.auth,
@@ -385,6 +348,8 @@ class IframeManager {
         this.modalContainer = null;
         this.styleElement = null;
         this.messageBroker = null;
+        // Guard flag to prevent double-binding event listeners
+        this.eventListenersBound = false;
         this.config = config;
         this.logger = new Logger(config.logging);
         this.deviceInfo = detectDevice();
@@ -424,18 +389,27 @@ class IframeManager {
     }
     /**
      * Create root container structure
+     * Reuses existing container if it has the same widgetId (singleton behavior)
      */
     createRootContainer() {
-        // Check if already exists
-        let existingContainer = document.getElementById('weld-container');
+        const existingContainer = document.getElementById('weld-container');
         if (existingContainer) {
-            this.logger.warn('Weld container already exists, removing old instance');
+            // Reuse if same widgetId
+            if (existingContainer.getAttribute('data-widget-id') === this.config.widgetId) {
+                this.logger.debug('Reusing existing root container');
+                this.rootContainer = existingContainer;
+                this.appContainer = existingContainer.querySelector('.weld-app');
+                this.modalContainer = document.getElementById('weld-modal-container');
+                return;
+            }
+            this.logger.warn('Weld container already exists with different widgetId, removing old instance');
             existingContainer.remove();
         }
         // Create root container
         this.rootContainer = document.createElement('div');
         this.rootContainer.id = 'weld-container';
         this.rootContainer.className = 'weld-namespace';
+        this.rootContainer.setAttribute('data-widget-id', this.config.widgetId);
         // Create app container
         this.appContainer = document.createElement('div');
         this.appContainer.className = 'weld-app';
@@ -470,17 +444,7 @@ class IframeManager {
      * Generate CSS for containers
      */
     generateCSS() {
-        const { customization } = this.config;
         return `
-      /* Weld Container */
-      #weld-container {
-        --weld-color-primary: ${customization.primaryColor};
-        --weld-color-accent: ${customization.accentColor};
-        --weld-font-family: ${customization.fontFamily};
-        --weld-font-size-base: ${customization.fontSize};
-        --weld-radius-xl: ${customization.borderRadius};
-      }
-
       /* Import main stylesheet */
       @import url('/styles/index.css');
 
@@ -504,6 +468,11 @@ class IframeManager {
      * Create launcher iframe
      */
     async createLauncherIframe() {
+        // Guard: skip if launcher iframe already exists
+        if (this.iframes.has(IframeType.LAUNCHER)) {
+            this.logger.debug('Launcher iframe already exists, skipping creation');
+            return;
+        }
         const { iframes } = this.config;
         const { launcher } = iframes;
         // Create container
@@ -531,9 +500,12 @@ class IframeManager {
       width: 100%;
       height: 100%;
       border: none;
-      background: transparent;
+      background: none;
+      color-scheme: none;
       display: block;
       pointer-events: auto;
+      border-radius: 50%;
+      filter: drop-shadow(rgba(9, 14, 21, 0.54) 0px 1px 6px) drop-shadow(rgba(9, 14, 21, 0.9) 0px 2px 32px);
     `;
         iframe.setAttribute('allow', 'clipboard-write');
         iframe.setAttribute('sandbox', 'allow-scripts allow-same-origin allow-forms allow-popups');
@@ -549,20 +521,36 @@ class IframeManager {
             createdAt: Date.now(),
         });
         // When DOM loads, notify MessageBroker to send weld:init
+        let launcherRetried = false;
         iframe.onload = () => {
             const metadata = this.iframes.get(IframeType.LAUNCHER);
             if (metadata) {
                 this.logger.debug('Launcher iframe DOM loaded');
-                // Notify MessageBroker that DOM is loaded (triggers weld:init)
                 this.messageBroker?.setIframeDomLoaded(IframeType.LAUNCHER);
             }
         };
+        iframe.onerror = () => {
+            this.logger.error('Launcher iframe failed to load');
+            if (!launcherRetried) {
+                launcherRetried = true;
+                this.logger.info('Retrying launcher iframe load...');
+                setTimeout(() => { iframe.src = this.buildIframeUrl(launcher.url); }, 3000);
+            }
+            else {
+                this.config.onError?.(new Error('Failed to load widget launcher'));
+            }
+        };
         this.logger.debug('Launcher iframe created');
     }
     /**
      * Create widget iframe
      */
     async createWidgetIframe() {
+        // Guard: skip if widget iframe already exists
+        if (this.iframes.has(IframeType.WIDGET)) {
+            this.logger.debug('Widget iframe already exists, skipping creation');
+            return;
+        }
         const { iframes } = this.config;
         const { widget } = iframes;
         // Create container
@@ -643,14 +631,25 @@ class IframeManager {
             createdAt: Date.now(),
         });
         // When DOM loads, notify MessageBroker to send weld:init
+        let widgetRetried = false;
         iframe.onload = () => {
             const metadata = this.iframes.get(IframeType.WIDGET);
             if (metadata) {
                 this.logger.debug('Widget iframe DOM loaded');
-                // Notify MessageBroker that DOM is loaded (triggers weld:init)
                 this.messageBroker?.setIframeDomLoaded(IframeType.WIDGET);
             }
         };
+        iframe.onerror = () => {
+            this.logger.error('Widget iframe failed to load');
+            if (!widgetRetried) {
+                widgetRetried = true;
+                this.logger.info('Retrying widget iframe load...');
+                setTimeout(() => { iframe.src = this.buildIframeUrl(widget.url); }, 3000);
+            }
+            else {
+                this.config.onError?.(new Error('Failed to load widget'));
+            }
+        };
         this.logger.debug('Widget iframe created');
     }
     /**
@@ -671,12 +670,21 @@ class IframeManager {
         url.searchParams.set('device', this.deviceInfo.type);
         url.searchParams.set('mobile', String(this.deviceInfo.isMobile));
         url.searchParams.set('parentOrigin', window.location.origin);
+        if (this.config.testMode) {
+            url.searchParams.set('testMode', 'true');
+        }
         return url.toString();
     }
     /**
      * Setup event listeners
      */
     setupEventListeners() {
+        // Guard: prevent double-binding
+        if (this.eventListenersBound) {
+            this.logger.debug('Event listeners already bound, skipping');
+            return;
+        }
+        this.eventListenersBound = true;
         // Window resize - use bound handler for proper cleanup
         window.addEventListener('resize', this.boundHandleResize);
         // Orientation change - use bound handler for proper cleanup
@@ -779,7 +787,7 @@ class IframeManager {
             iframe.container.style.transform = 'scale(1) translateY(0)';
         }
         // Handle mobile scroll lock
-        if (this.deviceInfo.isMobile && type === IframeType.WIDGET && this.config.mobile.scrollLock) {
+        if (this.deviceInfo.isMobile && type === IframeType.WIDGET) {
             document.body.classList.add('weld-mobile-open');
         }
         // Hide launcher on mobile when widget is open (full-screen mode)
@@ -878,6 +886,8 @@ class IframeManager {
         this.iframes.clear();
         // Clear messageBroker reference
         this.messageBroker = null;
+        // Reset guard flag
+        this.eventListenersBound = false;
         this.logger.info('IframeManager destroyed');
     }
 }
@@ -945,6 +955,8 @@ var MessageType;
     // Events
     MessageType["EVENT_TRACK"] = "weld:event:track";
     MessageType["ERROR_REPORT"] = "weld:error:report";
+    // Page tracking
+    MessageType["PAGE_CHANGE"] = "weld:page:change";
     // API responses
     MessageType["API_SUCCESS"] = "weld:api:success";
     MessageType["API_ERROR"] = "weld:api:error";
@@ -1484,8 +1496,6 @@ class MessageBroker {
             iframeType,
             config: {
                 api: this.config.api,
-                customization: this.config.customization,
-                features: this.config.features,
             },
         };
         const message = createMessage('weld:init', MessageOrigin.PARENT, initPayload);
@@ -2158,7 +2168,7 @@ class StateCoordinator {
     }
 }
 
-var version = "1.0.16";
+var version = "1.0.17";
 var packageJson = {
 	version: version};
 
@@ -2166,6 +2176,16 @@ var packageJson = {
  * Weld SDK - Main Entry Point
  * Public API for the Weld helpdesk widget
  */
+/**
+ * Module-level singleton registry keyed by widgetId
+ */
+const sdkRegistry = new Map();
+/**
+ * SessionStorage key helpers
+ */
+function openStateKey(widgetId) {
+    return `weld-widget-open-${widgetId}`;
+}
 /**
  * SDK initialization status
  */
@@ -2188,6 +2208,8 @@ class WeldSDK {
         this.readyResolve = null;
         // Subscription IDs for cleanup
         this.subscriptionIds = [];
+        // Page tracking cleanup
+        this.pageTrackingCleanup = null;
         /**
          * Update user attributes (Intercom-style, with rate limiting)
          * Limited to 20 calls per page load to prevent abuse
@@ -2226,6 +2248,13 @@ class WeldSDK {
             console.log('[Weld SDK] Received message:', event.data.type);
         }
         if (event.data?.type === 'launcher:clicked') {
+            if (this.status !== SDKStatus.READY) {
+                console.log('[Weld SDK] Launcher clicked but SDK not ready yet — waiting...');
+                this.readyPromise?.then(() => {
+                    this.handleLauncherClickMessage(event);
+                });
+                return;
+            }
             // Toggle behavior - if widget is open, close it; if closed, open it
             const state = this.stateCoordinator.getState();
             if (state.widget.isOpen) {
@@ -2238,9 +2267,24 @@ class WeldSDK {
             }
         }
         if (event.data?.type === 'weld:close') {
+            if (this.status !== SDKStatus.READY)
+                return;
             console.log('[Weld SDK] Widget close requested');
             this.close();
         }
+        if (event.data?.type === 'weld:unread-count') {
+            const count = event.data.count ?? 0;
+            // Forward to launcher iframe
+            const launcherIframe = this.iframeManager.getIframe(IframeType.LAUNCHER);
+            if (launcherIframe?.element?.contentWindow) {
+                launcherIframe.element.contentWindow.postMessage({
+                    type: 'weld:unread-count',
+                    count
+                }, '*');
+            }
+            // Update state coordinator for external API consumers
+            this.stateCoordinator.setBadgeCount(count);
+        }
         if (event.data?.type === 'weld:image:open' && event.data?.url) {
             this.showImageLightbox(event.data.url);
         }
@@ -2502,6 +2546,13 @@ class WeldSDK {
             this.logger.info('WeldSDK ready');
             // Call onReady callback
             this.config.onReady?.();
+            // Start tracking page URL changes
+            this.startPageTracking();
+            // Auto-open if widget was previously open (persisted in sessionStorage)
+            if (this.wasOpen()) {
+                this.logger.info('Restoring previously open widget from sessionStorage');
+                this.open();
+            }
         }
         catch (error) {
             this.status = SDKStatus.ERROR;
@@ -2580,6 +2631,58 @@ class WeldSDK {
     isReady() {
         return this.status === SDKStatus.READY;
     }
+    /**
+     * Update callbacks on an existing instance (used by singleton reuse)
+     */
+    updateCallbacks(config) {
+        if (config.onReady !== undefined)
+            this.config.onReady = config.onReady;
+        if (config.onOpen !== undefined)
+            this.config.onOpen = config.onOpen;
+        if (config.onClose !== undefined)
+            this.config.onClose = config.onClose;
+        if (config.onError !== undefined)
+            this.config.onError = config.onError;
+        if (config.onDestroy !== undefined)
+            this.config.onDestroy = config.onDestroy;
+        if (config.onMinimize !== undefined)
+            this.config.onMinimize = config.onMinimize;
+        if (config.onMaximize !== undefined)
+            this.config.onMaximize = config.onMaximize;
+    }
+    /**
+     * Persist open/closed state to sessionStorage
+     */
+    persistOpenState(isOpen) {
+        try {
+            sessionStorage.setItem(openStateKey(this.config.widgetId), isOpen ? 'true' : 'false');
+        }
+        catch {
+            // sessionStorage might not be available
+        }
+    }
+    /**
+     * Clear persisted state from sessionStorage
+     */
+    clearPersistedState() {
+        try {
+            sessionStorage.removeItem(openStateKey(this.config.widgetId));
+        }
+        catch {
+            // sessionStorage might not be available
+        }
+    }
+    /**
+     * Check if widget was previously open (from sessionStorage)
+     */
+    wasOpen() {
+        try {
+            return sessionStorage.getItem(openStateKey(this.config.widgetId)) === 'true';
+        }
+        catch {
+            return false;
+        }
+    }
     /**
      * Open the widget
      */
@@ -2598,6 +2701,7 @@ class WeldSDK {
         if (launcherIframe?.element?.contentWindow) {
             launcherIframe.element.contentWindow.postMessage({ type: 'weld:widget-opened' }, '*');
         }
+        this.persistOpenState(true);
         this.config.onOpen?.();
     }
     /**
@@ -2618,6 +2722,7 @@ class WeldSDK {
         if (launcherIframe?.element?.contentWindow) {
             launcherIframe.element.contentWindow.postMessage({ type: 'weld:widget-closed' }, '*');
         }
+        this.persistOpenState(false);
         this.config.onClose?.();
     }
     /**
@@ -2806,6 +2911,8 @@ class WeldSDK {
         });
         // Broadcast logout to iframes
         this.messageBroker.broadcast('weld:auth:logout', {});
+        // Clear persisted widget state
+        this.clearPersistedState();
         // Clear any stored session data
         try {
             const prefix = 'weld-';
@@ -2947,6 +3054,63 @@ class WeldSDK {
         this.logger.setLevel('warn');
         this.logger.info('Debug mode disabled');
     }
+    /**
+     * Send a page change message to the widget iframe
+     */
+    sendPageChange(url, title) {
+        const widgetIframe = this.iframeManager.getIframe(IframeType.WIDGET);
+        if (widgetIframe?.element?.contentWindow) {
+            widgetIframe.element.contentWindow.postMessage({
+                type: 'weld:page:change',
+                url,
+                title,
+                timestamp: Date.now(),
+            }, '*');
+        }
+    }
+    /**
+     * Start tracking page URL changes (SPA navigations + popstate)
+     */
+    startPageTracking() {
+        let lastUrl = window.location.href;
+        let debounceTimer = null;
+        const notifyChange = () => {
+            const currentUrl = window.location.href;
+            if (currentUrl !== lastUrl) {
+                lastUrl = currentUrl;
+                this.sendPageChange(currentUrl, document.title);
+            }
+        };
+        const debouncedNotify = () => {
+            if (debounceTimer)
+                clearTimeout(debounceTimer);
+            debounceTimer = setTimeout(notifyChange, 300);
+        };
+        // Send initial page
+        this.sendPageChange(window.location.href, document.title);
+        // Monkey-patch history.pushState and history.replaceState
+        const origPushState = history.pushState.bind(history);
+        const origReplaceState = history.replaceState.bind(history);
+        history.pushState = function (...args) {
+            origPushState(...args);
+            debouncedNotify();
+        };
+        history.replaceState = function (...args) {
+            origReplaceState(...args);
+            debouncedNotify();
+        };
+        // Listen for popstate (browser back/forward)
+        const handlePopstate = () => debouncedNotify();
+        window.addEventListener('popstate', handlePopstate);
+        // Store cleanup
+        this.pageTrackingCleanup = () => {
+            if (debounceTimer)
+                clearTimeout(debounceTimer);
+            window.removeEventListener('popstate', handlePopstate);
+            history.pushState = origPushState;
+            history.replaceState = origReplaceState;
+        };
+    }
     /**
      * Ensure SDK is ready before operation
      */
@@ -2955,11 +3119,26 @@ class WeldSDK {
             throw new Error('SDK not ready. Call init() first.');
         }
     }
+    /**
+     * Detach from the current component lifecycle without destroying the widget.
+     * Use this as a React useEffect cleanup — the widget stays alive across navigations.
+     */
+    detach() {
+        // No-op: widget stays alive in the singleton registry
+        this.logger.debug('WeldSDK detached (no-op, widget stays alive)');
+    }
     /**
      * Destroy SDK and cleanup
      */
     destroy() {
         this.logger.info('Destroying WeldSDK');
+        // Remove from singleton registry
+        sdkRegistry.delete(this.config.widgetId);
+        // Clear persisted state
+        this.clearPersistedState();
+        // Stop page tracking
+        this.pageTrackingCleanup?.();
+        this.pageTrackingCleanup = null;
         // Remove event listener using bound handler
         window.removeEventListener('message', this.boundHandleLauncherClick);
         // Unsubscribe from all message broker subscriptions