@helpway/react 0.16.0 → 0.17.1

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;
@@ -126,6 +132,14 @@ declare function useIdentify(): (data: IdentifyData) => Promise<void>;
 interface SupportProviderProps {
     apiKey: string;
     apiUrl?: string;
+    /**
+     * "mobile" when this is running inside @helpway/react-native's WebView.
+     * Travels to the server as a header on every call, because the server
+     * cannot work it out: the User-Agent in there is the phone's browser, so
+     * an app user and a website visitor on the same phone arrive identical.
+     * Defaults to web, which is what an embedding site is.
+     */
+    surface?: "web" | "mobile";
     locale?: string;
     initialConversationId?: string;
     deepLinkToken?: string;
@@ -154,7 +168,7 @@ interface SupportProviderProps {
  * 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, deepLinkToken, onReady, customLauncherSelector, onOpen, onClose, onUnreadChange, theme, children, }: SupportProviderProps): react_jsx_runtime.JSX.Element;
+declare function SupportProvider({ apiKey, apiUrl, surface, locale, initialConversationId, deepLinkToken, onReady, customLauncherSelector, onOpen, onClose, onUnreadChange, theme, children, }: SupportProviderProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Core widget state — connection status, visitor identity, website info.
@@ -319,16 +333,18 @@ declare function useAwaitingReply(): number;
  */
 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
@@ -578,4 +594,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, useAwaitingReply, 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 };