@helpway/react 0.15.3 → 0.17.0

package/dist/index.d.ts

@@ -67,6 +67,12 @@ interface HelpwayWidgetProps {
      * Only used when `placement="docked"`.
      */
     dockSuggestions?: readonly DockSuggestion[];
+    /**
+     * Render your own agent avatar (e.g. an animated mascot) wherever the
+     * widget shows the AI agent. Wins over the dashboard avatar image; an
+     * assigned human's photo still wins over it.
+     */
+    agentAvatar?: ReactNode;
     /**
      * CSS selector for a custom trigger element (e.g. `"#support-btn"`).
      * Clicking the matched element calls `Helpway.open()`. Combine with
@@ -103,7 +109,7 @@ type HelpwayPublicAPI = HelpwayMethods;
  * `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, deepLinkToken, onReady, hideLauncher, placement, colorScheme, dockSuggestions, customLauncherSelector, onOpen, onClose, onUnreadChange, theme, src, }: HelpwayWidgetProps): react_jsx_runtime.JSX.Element;
+declare function HelpwayWidget({ apiKey, apiUrl, locale, initialConversationId, deepLinkToken, onReady, hideLauncher, placement, colorScheme, dockSuggestions, agentAvatar, customLauncherSelector, onOpen, onClose, onUnreadChange, theme, src, }: HelpwayWidgetProps): react_jsx_runtime.JSX.Element;
 
 interface IdentifyData {
     externalId: string;
@@ -111,6 +117,13 @@ interface IdentifyData {
     name?: string;
     image?: string;
     metadata?: Record<string, unknown>;
+    /**
+     * Move this browser's visitor to the contact above even if it already
+     * belongs to a different contact. Dangerous: it merges whatever history
+     * this browser has into that contact. Off by default; without it the
+     * server keeps the existing link and returns that contact (#193).
+     */
+    reassign?: boolean;
 }
 /** Use a slice of the widget store with auto re-render */
 declare function useWidgetStore<T>(selector: (state: WidgetStore) => T): T;
@@ -174,6 +187,13 @@ declare function useWidget(): {
         name?: string;
         image?: string;
         metadata?: Record<string, unknown>;
+        /**
+         * Move this browser's visitor to the contact above even if it already
+         * belongs to a different contact. Dangerous: it merges whatever history
+         * this browser has into that contact. Off by default; without it the
+         * server keeps the existing link and returns that contact (#193).
+         */
+        reassign?: boolean;
     }) => Promise<any>;
 };
 
@@ -261,6 +281,30 @@ declare function useUnread(): {
     totalUnread: number;
 };
 
+/**
+ * How many conversations are waiting on the visitor to reply.
+ *
+ * Exists because `useUnread()` answers a question consumers usually do not have.
+ * A thread we answered two minutes ago and a thread the visitor closed
+ * themselves look identical in the widget — same row, same weight, no marker —
+ * and that is the moment a support thread dies: we reply, the visitor never
+ * registers it, the conversation is abandoned with an unanswered message in it.
+ *
+ * Counts human replies, not AI ones. An auto-reply follows nearly every visitor
+ * message, so including them leaves the indicator permanently lit for anyone who
+ * has ever opened the widget, which teaches people to ignore it.
+ *
+ * Written by hand in a downstream dashboard before it existed here; a
+ * `hideLauncher` integration badging its own trigger should not have to
+ * reimplement the rule.
+ *
+ * ```tsx
+ * const awaiting = useAwaitingReply();
+ * // "3 awaiting reply" — label it, do not just show the number
+ * ```
+ */
+declare function useAwaitingReply(): number;
+
 /**
  * Subscribe to raw WebSocket events.
  * For advanced usage — most apps should use useTimeline/usePresence instead.
@@ -271,19 +315,28 @@ declare function useUnread(): {
  *   if (event.type === 'timelineItemCreated') { ... }
  * })
  * ```
+ *
+ * The subscription lives as long as the socket instance, not as long as the
+ * handler's identity (#146). Callers pass inline arrows, which are new on every
+ * render; with `handler` in the effect deps that meant `handlers.delete` and
+ * `handlers.add` on every render above the caller, and any event that arrived
+ * between the two was dropped. The latest handler is kept in a ref and one
+ * stable wrapper is subscribed per socket.
  */
 declare function useRealtime(handler: (event: RealtimeEvent) => void): void;
 
+declare const AgentAvatarProvider: react.Provider<ReactNode>;
 /**
  * WidgetLogo — chat-header avatar. Renders WHO is talking to the
  * visitor right now. Resolution chain:
  *   1. Active conversation's assigned support user (assigneeName +
  *      assigneeImage from the widget API). When a human takes over a
  *      conversation the visitor sees that human, not the AI agent.
- *   2. Agent uploaded image (agentConfig.avatarUrl)
- *   3. Agent icon preset (avatarPreset + brandColor)
- *   4. Website logo (website.logoUrl)
- *   5. Helpway brand mark (octagonal) as the true last-resort fallback
+ *   2. Host-rendered avatar (`agentAvatar` prop, via AgentAvatarContext)
+ *   3. Agent uploaded image (agentConfig.avatarUrl)
+ *   4. Agent icon preset (avatarPreset + brandColor)
+ *   5. Website logo (website.logoUrl)
+ *   6. Helpway brand mark (octagonal) as the true last-resort fallback
  *
  * The `forceAgent` escape hatch skips the assignee lookup — used by
  * surfaces that mean "the agent" specifically (welcome card, conversation
@@ -474,6 +527,19 @@ interface AnnouncementPreviewsProps {
      * so its visual stays byte-identical to the original.
      */
     footer?: ReactNode;
+    /**
+     * How many cards to render before collapsing the rest into a single
+     * "+N more updates" row.
+     *
+     * Unlimited by default, which is what every existing consumer already gets.
+     * The launcher passes a real number because the strip above it is shared with
+     * the incoming-reply card and the two together ran off the top of the screen:
+     * four cards need more than 600px of viewport, and the topmost ones were
+     * simply gone. Clipping is a priority statement, not a size fix — a reply is a
+     * conversation waiting on the visitor, an announcement is content that can
+     * wait, so the announcements are what gets collapsed.
+     */
+    maxVisible?: number;
 }
 /**
  * `<AnnouncementPreviews>` — proactive "new content" cards shown when
@@ -490,7 +556,7 @@ interface AnnouncementPreviewsProps {
  *
  * Must be rendered inside `<SupportProvider>`.
  */
-declare function AnnouncementPreviews({ onOpen, avatar, placement, footer, }: AnnouncementPreviewsProps): react_jsx_runtime.JSX.Element | null;
+declare function AnnouncementPreviews({ onOpen, avatar, placement, footer, maxVisible, }: AnnouncementPreviewsProps): react_jsx_runtime.JSX.Element | null;
 
 /**
  * Lightweight Markdown → HTML renderer.
@@ -520,4 +586,4 @@ declare function MarkdownContent({ bodyHtml, bodyMarkdown, className, }: {
     className?: string;
 }): react_jsx_runtime.JSX.Element | null;
 
-export { type AnnouncementPreviewEntry, AnnouncementPreviews, type AnnouncementPreviewsPlacement, type AnnouncementPreviewsProps, Composer, DefaultWidget, type HelpwayPublicAPI, HelpwayWidget, type HelpwayWidgetProps, type IdentifyData, MarkdownContent, MessageBubble, MessageList, MessagePreview, type MessagePreviewPlacement, type MessagePreviewProps, SupportProvider, WidgetLogo, linkifyText, renderMarkdown, useComposer, useConversations, useIdentify, usePresence, useRealtime, useTimeline, useUnread, useWidget, useWidgetStore };
+export { AgentAvatarProvider, type AnnouncementPreviewEntry, AnnouncementPreviews, type AnnouncementPreviewsPlacement, type AnnouncementPreviewsProps, Composer, DefaultWidget, type HelpwayPublicAPI, HelpwayWidget, type HelpwayWidgetProps, type IdentifyData, MarkdownContent, MessageBubble, MessageList, MessagePreview, type MessagePreviewPlacement, type MessagePreviewProps, SupportProvider, WidgetLogo, linkifyText, renderMarkdown, useAwaitingReply, useComposer, useConversations, useIdentify, usePresence, useRealtime, useTimeline, useUnread, useWidget, useWidgetStore };