@helpway/react 0.3.4 → 0.4.0

package/dist/index.d.ts

@@ -1,48 +1,12 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as _helpway_widget_core from '@helpway/widget-core';
-import { WidgetStore } from '@helpway/widget-core';
-export { ConversationSummary, RealtimeEvent, TimelineItem, WidgetState, WidgetStore, clearVisitorId, formatRelativeTime, formatTime, getInitials, getOrCreateVisitorId } from '@helpway/widget-core';
+import { HelpwayAPI, WidgetStore } from '@helpway/widget-core';
+export { ConversationSummary, HelpwayAPI, RealtimeEvent, TimelineItem, WidgetEventName, WidgetEvents, WidgetState, WidgetStore, clearVisitorId, formatRelativeTime, formatTime, getInitials, getOrCreateVisitorId } from '@helpway/widget-core';
 import * as react from 'react';
 import react__default, { ReactNode } from 'react';
 import * as _helpway_types from '@helpway/types';
 import { TimelineItem, RealtimeEvent, TimelineItemPart } from '@helpway/types';
 
-interface IdentifyData {
-    externalId: string;
-    email?: string;
-    name?: string;
-    image?: string;
-    metadata?: Record<string, unknown>;
-}
-/** Use a slice of the widget store with auto re-render */
-declare function useWidgetStore<T>(selector: (state: WidgetStore) => T): T;
-/** Hook to identify the current visitor (link to customer contact) */
-declare function useIdentify(): (data: IdentifyData) => Promise<void>;
-interface SupportProviderProps {
-    /** Public API key (pk_xxx) */
-    apiKey: string;
-    /** API base URL (default: auto-detect from script tag or window) */
-    apiUrl?: string;
-    /** Widget locale (e.g., "fr", "de"). Falls back to navigator.language → "en" */
-    locale?: string;
-    /** Deep link: auto-open this conversation after bootstrap (from ?hw_conv= URL param) */
-    initialConversationId?: string;
-    /** Callback to expose widget API to parent (for embed loader) */
-    onReady?: (api: {
-        identify: (data: IdentifyData) => Promise<void>;
-        openConversation: (id: string) => void;
-    }) => void;
-    children: ReactNode;
-}
-/**
- * Root provider for the Helpway widget.
- * Creates tRPC client, WebSocket connection, and state store.
- *
- * Visitor identity is managed via server-side cookies (hw_visitor).
- * No localStorage or client-side ID management needed.
- */
-declare function SupportProvider({ apiKey, apiUrl, locale, initialConversationId, onReady, children, }: SupportProviderProps): react_jsx_runtime.JSX.Element;
-
 interface HelpwayWidgetProps {
     /**
      * Public API key from the Helpway dashboard. Required.
@@ -67,12 +31,27 @@ interface HelpwayWidgetProps {
     initialConversationId?: string;
     /**
      * Called once after the widget has bootstrapped and exposes
-     * programmatic APIs (identify, openConversation).
+     * the full programmatic API object (also available as `window.Helpway`).
      */
-    onReady?: (api: {
-        identify: (data: IdentifyData) => Promise<void>;
-        openConversation: (id: string) => void;
-    }) => void;
+    onReady?: (api: HelpwayPublicAPI) => void;
+    /**
+     * Hide the default floating launcher button. Use with
+     * `customLauncherSelector` or `window.Helpway.open()` to trigger
+     * the widget from your own UI.
+     */
+    hideLauncher?: boolean;
+    /**
+     * CSS selector for a custom trigger element (e.g. `"#support-btn"`).
+     * Clicking the matched element calls `Helpway.open()`. Combine with
+     * `hideLauncher` to fully replace the default bubble.
+     */
+    customLauncherSelector?: string;
+    /** Fires when the widget panel opens */
+    onOpen?: () => void;
+    /** Fires when the widget panel closes */
+    onClose?: () => void;
+    /** Fires when the unread count changes */
+    onUnreadChange?: (count: number) => void;
     /**
      * @deprecated Legacy prop from the v0.1 script-loader era. If set,
      * the `/widget.js` suffix is stripped to derive `apiUrl`. New code
@@ -80,12 +59,46 @@ interface HelpwayWidgetProps {
      */
     src?: string;
 }
+
+type HelpwayPublicAPI = HelpwayAPI;
 /**
  * Render this once at the root of your app (e.g. in `_app.tsx`,
  * `layout.tsx`, or `main.tsx`). Unmounting cleanly tears down the
  * widget and its WebSocket connection — useful for route-scoped mounts.
  */
-declare function HelpwayWidget({ apiKey, apiUrl, locale, initialConversationId, onReady, src, }: HelpwayWidgetProps): react_jsx_runtime.JSX.Element;
+declare function HelpwayWidget({ apiKey, apiUrl, locale, initialConversationId, onReady, hideLauncher, customLauncherSelector, onOpen, onClose, onUnreadChange, src, }: HelpwayWidgetProps): react_jsx_runtime.JSX.Element;
+
+interface IdentifyData {
+    externalId: string;
+    email?: string;
+    name?: string;
+    image?: string;
+    metadata?: Record<string, unknown>;
+}
+/** Use a slice of the widget store with auto re-render */
+declare function useWidgetStore<T>(selector: (state: WidgetStore) => T): T;
+/** Hook to identify the current visitor (link to customer contact) */
+declare function useIdentify(): (data: IdentifyData) => Promise<void>;
+interface SupportProviderProps {
+    apiKey: string;
+    apiUrl?: string;
+    locale?: string;
+    initialConversationId?: string;
+    onReady?: (api: HelpwayAPI) => void;
+    customLauncherSelector?: string;
+    onOpen?: () => void;
+    onClose?: () => void;
+    onUnreadChange?: (count: number) => void;
+    children: ReactNode;
+}
+/**
+ * Root provider for the Helpway widget.
+ * Creates tRPC client, WebSocket connection, and state store.
+ *
+ * Visitor identity is managed via server-side cookies (hw_visitor).
+ * No localStorage or client-side ID management needed.
+ */
+declare function SupportProvider({ apiKey, apiUrl, locale, initialConversationId, onReady, customLauncherSelector, onOpen, onClose, onUnreadChange, children, }: SupportProviderProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Core widget state — connection status, visitor identity, website info.
@@ -216,8 +229,8 @@ declare function useRealtime(handler: (event: RealtimeEvent) => void): void;
  * Unified support widget — Intercom-style with tab navigation.
  * Two tabs: Home + Messages. Sub-views: conversation + new conversation.
  */
-declare function DefaultWidget({ initialOpen }?: {
-    initialOpen?: boolean;
+declare function DefaultWidget({ hideLauncher }?: {
+    hideLauncher?: boolean;
 }): react_jsx_runtime.JSX.Element;
 
 interface MessageBubbleProps {
@@ -292,4 +305,4 @@ declare function MarkdownContent({ bodyHtml, bodyMarkdown, className, }: {
     className?: string;
 }): react_jsx_runtime.JSX.Element | null;
 
-export { Composer, DefaultWidget, HelpwayWidget, type HelpwayWidgetProps, type IdentifyData, MarkdownContent, MessageBubble, MessageList, SupportProvider, linkifyText, renderMarkdown, useComposer, useConversations, useIdentify, usePresence, useRealtime, useTimeline, useUnread, useWidget, useWidgetStore };
+export { Composer, DefaultWidget, type HelpwayPublicAPI, HelpwayWidget, type HelpwayWidgetProps, type IdentifyData, MarkdownContent, MessageBubble, MessageList, SupportProvider, linkifyText, renderMarkdown, useComposer, useConversations, useIdentify, usePresence, useRealtime, useTimeline, useUnread, useWidget, useWidgetStore };

package/dist/index.js

@@ -221,8 +221,10 @@ function createWidgetStore() {
     typingUsers: /* @__PURE__ */ new Map(),
     aiProcessing: /* @__PURE__ */ new Map(),
     isOpen: false,
+    isDismissed: false,
     view: "home",
     incomingPreview: null,
+    newConversationPrefill: null,
     contentCache: /* @__PURE__ */ new Map(),
     // ── Lifecycle ────────────────────────────────────
     setReady(visitor, website, agentConfig) {
@@ -377,12 +379,17 @@ function createWidgetStore() {
       set((s) => ({
         isOpen: open,
         incomingPreview: open ? null : s.incomingPreview
-        // dismiss preview when opening
       }));
     },
+    setDismissed(dismissed) {
+      set({ isDismissed: dismissed });
+    },
     setView(view) {
       set({ view });
     },
+    setNewConversationPrefill(text) {
+      set({ newConversationPrefill: text });
+    },
     dismissPreview() {
       set({ incomingPreview: null });
     },
@@ -488,6 +495,97 @@ function createWidgetStore() {
   }));
 }
 
+// ../widget-core/src/api.ts
+function createHelpwayAPI(deps) {
+  const { store, emitter, identify, apiKey } = deps;
+  return {
+    open() {
+      store.getState().setOpen(true);
+      store.getState().setDismissed(false);
+    },
+    close() {
+      store.getState().setOpen(false);
+    },
+    toggle() {
+      const s = store.getState();
+      if (s.isDismissed) {
+        s.setDismissed(false);
+        s.setOpen(true);
+        emitter.emit("show");
+      } else {
+        s.setOpen(!s.isOpen);
+      }
+    },
+    dismiss() {
+      store.getState().setOpen(false);
+      store.getState().setDismissed(true);
+      emitter.emit("dismiss");
+    },
+    show() {
+      store.getState().setDismissed(false);
+      emitter.emit("show");
+    },
+    shutdown() {
+      store.getState().setOpen(false);
+      store.getState().setDismissed(false);
+      clearVisitorId(apiKey);
+      if (typeof document !== "undefined") {
+        document.cookie = "hw_visitor=; Path=/; Max-Age=0";
+      }
+    },
+    identify,
+    newConversation(prefill) {
+      const s = store.getState();
+      s.setDismissed(false);
+      s.setOpen(true);
+      s.setNewConversationPrefill(prefill ?? "");
+    },
+    openConversation(id) {
+      const s = store.getState();
+      s.setDismissed(false);
+      s.setActiveConversation(id);
+      s.setOpen(true);
+    },
+    get unreadCount() {
+      return store.getState().conversations.reduce((sum, c) => sum + c.unreadCount, 0);
+    },
+    get isOpen() {
+      return store.getState().isOpen;
+    },
+    on(event, fn) {
+      emitter.on(event, fn);
+    },
+    off(event, fn) {
+      emitter.off(event, fn);
+    }
+  };
+}
+
+// ../widget-core/src/events.ts
+var WidgetEventEmitter = class {
+  listeners = /* @__PURE__ */ new Map();
+  on(event, fn) {
+    if (!this.listeners.has(event)) this.listeners.set(event, /* @__PURE__ */ new Set());
+    this.listeners.get(event).add(fn);
+  }
+  off(event, fn) {
+    this.listeners.get(event)?.delete(fn);
+  }
+  emit(event, ...args) {
+    const data = args[0];
+    this.listeners.get(event)?.forEach((fn) => {
+      try {
+        fn(data);
+      } catch (err) {
+        console.error(`[Helpway] Event handler error (${event}):`, err);
+      }
+    });
+  }
+  removeAll() {
+    this.listeners.clear();
+  }
+};
+
 // ../widget-core/src/i18n.ts
 var en = {
   // Navigation & tabs
@@ -758,6 +856,10 @@ function SupportProvider({
   locale,
   initialConversationId,
   onReady,
+  customLauncherSelector,
+  onOpen,
+  onClose,
+  onUnreadChange,
   children
 }) {
   const initRef = useRef(null);
@@ -771,6 +873,7 @@ function SupportProvider({
       apiKey
     });
     const store2 = createWidgetStore();
+    const emitter2 = new WidgetEventEmitter();
     const ws2 = new WebSocketManager({
       apiUrl: resolvedApiUrl,
       visitorId: "",
@@ -794,9 +897,13 @@ function SupportProvider({
         console.error("[Helpway] identify failed:", err);
       }
     };
-    initRef.current = { client: client2, store: store2, ws: ws2, identify: identify2 };
+    const api2 = createHelpwayAPI({ store: store2, emitter: emitter2, identify: identify2, apiKey });
+    if (typeof window !== "undefined") {
+      window.Helpway = api2;
+    }
+    initRef.current = { client: client2, store: store2, ws: ws2, identify: identify2, api: api2, emitter: emitter2 };
   }
-  const { client, store, ws, identify } = initRef.current;
+  const { client, store, ws, identify, api, emitter } = initRef.current;
   const retryBootstrap = useCallback(() => {
     setHasBootstrapError(false);
     setBootstrapAttempt((n) => n + 1);
@@ -851,11 +958,8 @@ function SupportProvider({
           store.getState().setActiveConversation(initialConversationId);
           store.getState().setOpen(true);
         }
-        const openConversation = (id) => {
-          store.getState().setActiveConversation(id);
-          store.getState().setOpen(true);
-        };
-        onReady?.({ identify: initRef.current.identify, openConversation });
+        emitter.emit("ready");
+        onReady?.(initRef.current.api);
       } catch (err) {
         console.error("[Helpway] Bootstrap failed:", err);
         if (!cancelled) {
@@ -879,6 +983,13 @@ function SupportProvider({
       if (event.type === "timelineItemCreated") {
         const item = event.item;
         const isPublicIncoming = item?.visibility === "public" && !item.visitorId;
+        if (isPublicIncoming && item?.text) {
+          emitter.emit("messageReceived", {
+            conversationId: event.conversationId,
+            text: item.text,
+            senderName: "aiAgentId" in item && item.aiAgentId ? "AI" : null
+          });
+        }
         if (!isPublicIncoming) return;
         const s = store.getState();
         const isViewing = s.isOpen && s.activeConversationId === event.conversationId;
@@ -901,11 +1012,68 @@ function SupportProvider({
       setLocale(locale);
     }
   }, [locale]);
+  useEffect(() => {
+    const unsub = store.subscribe((state, prev) => {
+      if (state.isOpen && !prev.isOpen) {
+        emitter.emit("open");
+        onOpen?.();
+      }
+      if (!state.isOpen && prev.isOpen) {
+        emitter.emit("close");
+        onClose?.();
+      }
+      const prevUnread = prev.conversations.reduce((s, c) => s + c.unreadCount, 0);
+      const nextUnread = state.conversations.reduce((s, c) => s + c.unreadCount, 0);
+      if (nextUnread !== prevUnread) {
+        emitter.emit("unreadChange", nextUnread);
+        onUnreadChange?.(nextUnread);
+      }
+    });
+    return unsub;
+  }, [store, emitter, onOpen, onClose, onUnreadChange]);
+  useEffect(() => {
+    if (!customLauncherSelector) return;
+    const handler = (e) => {
+      e.preventDefault();
+      api.toggle();
+    };
+    const attach = () => {
+      const el2 = document.querySelector(customLauncherSelector);
+      if (el2) {
+        el2.addEventListener("click", handler);
+        return el2;
+      }
+      return null;
+    };
+    let el = attach();
+    let observer = null;
+    if (!el) {
+      observer = new MutationObserver(() => {
+        el = attach();
+        if (el) observer?.disconnect();
+      });
+      observer.observe(document.body, { childList: true, subtree: true });
+    }
+    return () => {
+      el?.removeEventListener("click", handler);
+      observer?.disconnect();
+    };
+  }, [customLauncherSelector, api]);
+  useEffect(() => {
+    return () => {
+      if (window.Helpway === api) {
+        window.Helpway = void 0;
+      }
+      emitter.removeAll();
+    };
+  }, [api, emitter]);
   const ctxValue = {
     client,
     store,
     ws,
     identify,
+    api,
+    emitter,
     hasBootstrapError,
     wsDisconnected,
     retryBootstrap
@@ -3381,12 +3549,13 @@ function AgentPresetIcon({ presetId }) {
     )
   );
 }
-function DefaultWidget({ initialOpen = false } = {}) {
+function DefaultWidget({ hideLauncher = false } = {}) {
   const { isReady, website, agentConfig } = useWidget();
   useI18n();
   const { client, store, hasBootstrapError, wsDisconnected, retryBootstrap } = useWidgetContext();
   const { conversations, create, isCreating, setActiveConversation } = useConversations();
   const activeId = useWidgetStore((s) => s.activeConversationId);
+  const isDismissed = useWidgetStore((s) => s.isDismissed);
   const { totalUnread } = useUnread();
   const contentTabs = useWidgetStore((s) => s.agentConfig?.contentTabs) ?? EMPTY_CONTENT_TABS;
   const visitorContact = useWidgetStore((s) => s.visitor?.contact);
@@ -3397,13 +3566,30 @@ function DefaultWidget({ initialOpen = false } = {}) {
       activeId
     });
   }
-  const [isOpen, setIsOpen] = useState12(initialOpen);
+  const storeIsOpen = useWidgetStore((s) => s.isOpen);
   const [isClosing, setIsClosing] = useState12(false);
+  const isOpen = storeIsOpen || isClosing;
   const [activeTab, setActiveTab] = useState12("home");
   const [subView, setSubView] = useState12(null);
   const [newText, setNewText] = useState12("");
   const [contentDetailSlug, setContentDetailSlug] = useState12(null);
   const [contentCategoryName, setContentCategoryName] = useState12(null);
+  const prevActiveIdRef = useRef13(activeId);
+  useEffect11(() => {
+    if (activeId && activeId !== prevActiveIdRef.current && subView !== "conversation") {
+      setSubView("conversation");
+    }
+    prevActiveIdRef.current = activeId;
+  }, [activeId, subView]);
+  const prefill = useWidgetStore((s) => s.newConversationPrefill);
+  useEffect11(() => {
+    if (prefill !== null) {
+      if (prefill.length > 0) setNewText(prefill);
+      setSubView("new");
+      setActiveTab("home");
+      store.getState().setNewConversationPrefill(null);
+    }
+  }, [prefill, store]);
   const closeTimerRef = useRef13(void 0);
   const welcomeMsgRaw = agentConfig?.welcomeMessage;
   const welcomeIsFactoryDefault = !welcomeMsgRaw || welcomeMsgRaw === DEFAULT_EN_WELCOME;
@@ -3482,9 +3668,9 @@ function DefaultWidget({ initialOpen = false } = {}) {
     },
     [activeTab, subView, activeId, setActiveConversation]
   );
-  const storeSetOpen = useWidgetStore((s) => s.setOpen);
+  const setStoreOpen = useWidgetStore((s) => s.setOpen);
   const handleBubbleClick = useCallback12(() => {
-    if (isOpen) {
+    if (storeIsOpen) {
       const leavingId = store.getState().activeConversationId;
       if (leavingId && !leavingId.startsWith("temp-")) {
         store.getState().clearUnread(leavingId);
@@ -3493,18 +3679,16 @@ function DefaultWidget({ initialOpen = false } = {}) {
       }
       setIsClosing(true);
       closeTimerRef.current = setTimeout(() => {
-        setIsOpen(false);
         setIsClosing(false);
-        storeSetOpen(false);
+        setStoreOpen(false);
       }, 200);
     } else {
-      setIsOpen(true);
       setIsClosing(false);
       setSubView(null);
       setActiveTab("home");
-      storeSetOpen(true);
+      setStoreOpen(true);
     }
-  }, [isOpen, storeSetOpen, client, store]);
+  }, [storeIsOpen, setStoreOpen, client, store]);
   const handleClose = useCallback12(() => {
     const leavingId = store.getState().activeConversationId;
     if (leavingId && !leavingId.startsWith("temp-")) {
@@ -3514,11 +3698,10 @@ function DefaultWidget({ initialOpen = false } = {}) {
     }
     setIsClosing(true);
     closeTimerRef.current = setTimeout(() => {
-      setIsOpen(false);
       setIsClosing(false);
-      storeSetOpen(false);
+      setStoreOpen(false);
     }, 200);
-  }, [storeSetOpen, client, store]);
+  }, [setStoreOpen, client, store]);
   const handleNewConversation = useCallback12(async () => {
     const trimmed = newText.trim();
     if (!trimmed || isCreating) return;
@@ -3890,9 +4073,9 @@ function DefaultWidget({ initialOpen = false } = {}) {
             ]
           }
         ),
-        !isOpen && /* @__PURE__ */ jsx13(MessagePreview, { onOpen: handleBubbleClick }),
+        !isOpen && !isDismissed && !hideLauncher && /* @__PURE__ */ jsx13(MessagePreview, { onOpen: handleBubbleClick }),
         /* @__PURE__ */ jsx13(WidgetDebugOverlay, {}),
-        /* @__PURE__ */ jsxs8(
+        !isDismissed && !hideLauncher && /* @__PURE__ */ jsxs8(
           "button",
           {
             ref: bubbleRef,
@@ -4427,6 +4610,11 @@ function HelpwayWidget({
   locale,
   initialConversationId,
   onReady,
+  hideLauncher,
+  customLauncherSelector,
+  onOpen,
+  onClose,
+  onUnreadChange,
   // eslint-disable-next-line @typescript-eslint/no-deprecated
   src
 }) {
@@ -4439,7 +4627,11 @@ function HelpwayWidget({
       locale,
       initialConversationId,
       onReady,
-      children: /* @__PURE__ */ jsx14(DefaultWidget, {})
+      customLauncherSelector,
+      onOpen,
+      onClose,
+      onUnreadChange,
+      children: /* @__PURE__ */ jsx14(DefaultWidget, { hideLauncher })
     }
   );
 }