@clivly/chat-widget 0.14.1 → 0.16.0

package/dist/browser.d.cts

@@ -1,5 +1,26 @@
 import { Root } from "react-dom/client";
 import { CSSProperties } from "react";
+//#region src/layout.d.ts
+/**
+ * Where the widget sits on the host page, and what its launcher looks like.
+ *
+ * Until 0.16 the widget rendered in normal flow wherever it was mounted — the
+ * script tag inserted it directly after itself, so most embeds showed a
+ * full-width-label pill at the end of the page rather than a floating button.
+ * Floating in a corner is now the default; `"inline"` keeps the old behaviour
+ * for a host that positions the widget itself.
+ */
+type ChatWidgetPlacement = "bottom-left" | "bottom-right" | "inline";
+/**
+ * - `"auto"` (default): the labelled pill on wide screens, a 48px icon-only
+ *   button below 48rem, where a pill covers the host's own controls.
+ * - `"pill"`: always the labelled pill.
+ * - `"icon"`: always the icon-only button.
+ *
+ * The label stays the button's accessible name in every variant.
+ */
+type ChatWidgetLauncher = "auto" | "icon" | "pill";
+//#endregion
 //#region src/theme.d.ts
 /**
  * Theme resolution for the widget.
@@ -34,11 +55,30 @@ interface WidgetSummary {
 }
 interface WidgetMessage {
   author: string | null;
+  /**
+   * Set on messages the support assistant wrote (`greeting`, `topic`,
+   * `handoff`, `ai`, `ai_clarify`) and on a visitor's topic click
+   * (`topic_choice`). Absent or null on everything a person typed, and on
+   * every message from a server that predates the assistant.
+   */
+  automation?: string | null;
   body: string;
   createdAt: string;
   id: string;
   senderType: WidgetSenderType;
 }
+type WidgetSupportState = "automated" | "handoff" | "human";
+interface WidgetSupportTopic {
+  action: "answer" | "ask" | "link" | "human";
+  id: string;
+  label: string;
+}
+/** Guided support for one conversation. Answers stay on the server. */
+interface WidgetSupport {
+  mode: "human" | "guided" | "ai";
+  state: WidgetSupportState | null;
+  topics: WidgetSupportTopic[];
+}
 interface WidgetSessionPayload {
   contact: WidgetContact | null;
   conversation: WidgetConversation;
@@ -46,6 +86,8 @@ interface WidgetSessionPayload {
   messages: WidgetMessage[];
   /** Absolute socket URL returned by Clivly's bootstrap. */
   socketUrl?: string;
+  /** Absent or null when the widget has no guided support configured. */
+  support?: WidgetSupport | null;
   token: string;
   visitorToken: string;
   widget: WidgetSummary;
@@ -65,6 +107,12 @@ interface WidgetClientCreateMessageEvent {
   id: string;
   type: "message.create";
 }
+/** The visitor picked a guided topic (see `ChatTransportConnection.selectTopic`). */
+interface WidgetClientTopicEvent {
+  id: string;
+  topicId: string;
+  type: "topic.select";
+}
 interface WidgetSessionReadyEvent {
   conversationId: string;
   type: "session.ready";
@@ -83,11 +131,20 @@ interface WidgetMessageAckEvent {
   message: WidgetMessage;
   type: "message.ack";
 }
+interface WidgetSupportStateEvent {
+  state: WidgetSupportState;
+  type: "support.state";
+}
+/** The assistant is preparing an answer (`thinking`) or has finished (`idle`). */
+interface WidgetAssistantStatusEvent {
+  status: "thinking" | "idle";
+  type: "assistant.status";
+}
 interface WidgetErrorEvent {
   message: string;
   type: "error";
 }
-type WidgetServerEvent = WidgetConversationSnapshotEvent | WidgetErrorEvent | WidgetMessageAckEvent | WidgetMessageCreatedEvent | WidgetSessionReadyEvent;
+type WidgetServerEvent = WidgetAssistantStatusEvent | WidgetConversationSnapshotEvent | WidgetErrorEvent | WidgetMessageAckEvent | WidgetMessageCreatedEvent | WidgetSessionReadyEvent | WidgetSupportStateEvent;
 //#endregion
 //#region src/transport.d.ts
 interface ChatTransportHandlers {
@@ -104,6 +161,11 @@ interface ChatTransportConnection {
    * without it still works, its visitors are just emailed replies they saw.
    */
   markRead?: () => void;
+  /**
+   * Send a guided-topic click. Optional: without it the widget sends the
+   * topic's label as an ordinary message, so a custom transport still works.
+   */
+  selectTopic?: (event: WidgetClientTopicEvent) => void;
   sendMessage: (event: WidgetClientCreateMessageEvent) => void;
 }
 interface CreateChatTransportOptions {
@@ -136,7 +198,17 @@ interface ChatWidgetProps {
   defaultVisitor?: Partial<ChatWidgetVisitor>;
   getSession: GetSession;
   initiallyOpen?: boolean;
+  /** Launcher shape; see {@link ChatWidgetLauncher}. Defaults to `"auto"`. */
+  launcher?: ChatWidgetLauncher;
+  /** The launcher's visible text, and always its accessible name. */
   launcherLabel?: string;
+  /**
+   * Where the widget sits; see {@link ChatWidgetPlacement}. Defaults to
+   * `"bottom-right"`, floating clear of the device's safe-area insets. Stacks
+   * at `--clivly-chat-z-index` (default 2147483000) — lower it through
+   * `style` to sit beneath the host's own dialogs.
+   */
+  placement?: ChatWidgetPlacement;
   storage?: Pick<Storage, "getItem" | "setItem">;
   /**
    * Inline styles on the widget root. The intended use is overriding palette

package/dist/browser.d.mts

@@ -1,5 +1,26 @@
 import { Root } from "react-dom/client";
 import { CSSProperties } from "react";
+//#region src/layout.d.ts
+/**
+ * Where the widget sits on the host page, and what its launcher looks like.
+ *
+ * Until 0.16 the widget rendered in normal flow wherever it was mounted — the
+ * script tag inserted it directly after itself, so most embeds showed a
+ * full-width-label pill at the end of the page rather than a floating button.
+ * Floating in a corner is now the default; `"inline"` keeps the old behaviour
+ * for a host that positions the widget itself.
+ */
+type ChatWidgetPlacement = "bottom-left" | "bottom-right" | "inline";
+/**
+ * - `"auto"` (default): the labelled pill on wide screens, a 48px icon-only
+ *   button below 48rem, where a pill covers the host's own controls.
+ * - `"pill"`: always the labelled pill.
+ * - `"icon"`: always the icon-only button.
+ *
+ * The label stays the button's accessible name in every variant.
+ */
+type ChatWidgetLauncher = "auto" | "icon" | "pill";
+//#endregion
 //#region src/theme.d.ts
 /**
  * Theme resolution for the widget.
@@ -34,11 +55,30 @@ interface WidgetSummary {
 }
 interface WidgetMessage {
   author: string | null;
+  /**
+   * Set on messages the support assistant wrote (`greeting`, `topic`,
+   * `handoff`, `ai`, `ai_clarify`) and on a visitor's topic click
+   * (`topic_choice`). Absent or null on everything a person typed, and on
+   * every message from a server that predates the assistant.
+   */
+  automation?: string | null;
   body: string;
   createdAt: string;
   id: string;
   senderType: WidgetSenderType;
 }
+type WidgetSupportState = "automated" | "handoff" | "human";
+interface WidgetSupportTopic {
+  action: "answer" | "ask" | "link" | "human";
+  id: string;
+  label: string;
+}
+/** Guided support for one conversation. Answers stay on the server. */
+interface WidgetSupport {
+  mode: "human" | "guided" | "ai";
+  state: WidgetSupportState | null;
+  topics: WidgetSupportTopic[];
+}
 interface WidgetSessionPayload {
   contact: WidgetContact | null;
   conversation: WidgetConversation;
@@ -46,6 +86,8 @@ interface WidgetSessionPayload {
   messages: WidgetMessage[];
   /** Absolute socket URL returned by Clivly's bootstrap. */
   socketUrl?: string;
+  /** Absent or null when the widget has no guided support configured. */
+  support?: WidgetSupport | null;
   token: string;
   visitorToken: string;
   widget: WidgetSummary;
@@ -65,6 +107,12 @@ interface WidgetClientCreateMessageEvent {
   id: string;
   type: "message.create";
 }
+/** The visitor picked a guided topic (see `ChatTransportConnection.selectTopic`). */
+interface WidgetClientTopicEvent {
+  id: string;
+  topicId: string;
+  type: "topic.select";
+}
 interface WidgetSessionReadyEvent {
   conversationId: string;
   type: "session.ready";
@@ -83,11 +131,20 @@ interface WidgetMessageAckEvent {
   message: WidgetMessage;
   type: "message.ack";
 }
+interface WidgetSupportStateEvent {
+  state: WidgetSupportState;
+  type: "support.state";
+}
+/** The assistant is preparing an answer (`thinking`) or has finished (`idle`). */
+interface WidgetAssistantStatusEvent {
+  status: "thinking" | "idle";
+  type: "assistant.status";
+}
 interface WidgetErrorEvent {
   message: string;
   type: "error";
 }
-type WidgetServerEvent = WidgetConversationSnapshotEvent | WidgetErrorEvent | WidgetMessageAckEvent | WidgetMessageCreatedEvent | WidgetSessionReadyEvent;
+type WidgetServerEvent = WidgetAssistantStatusEvent | WidgetConversationSnapshotEvent | WidgetErrorEvent | WidgetMessageAckEvent | WidgetMessageCreatedEvent | WidgetSessionReadyEvent | WidgetSupportStateEvent;
 //#endregion
 //#region src/transport.d.ts
 interface ChatTransportHandlers {
@@ -104,6 +161,11 @@ interface ChatTransportConnection {
    * without it still works, its visitors are just emailed replies they saw.
    */
   markRead?: () => void;
+  /**
+   * Send a guided-topic click. Optional: without it the widget sends the
+   * topic's label as an ordinary message, so a custom transport still works.
+   */
+  selectTopic?: (event: WidgetClientTopicEvent) => void;
   sendMessage: (event: WidgetClientCreateMessageEvent) => void;
 }
 interface CreateChatTransportOptions {
@@ -136,7 +198,17 @@ interface ChatWidgetProps {
   defaultVisitor?: Partial<ChatWidgetVisitor>;
   getSession: GetSession;
   initiallyOpen?: boolean;
+  /** Launcher shape; see {@link ChatWidgetLauncher}. Defaults to `"auto"`. */
+  launcher?: ChatWidgetLauncher;
+  /** The launcher's visible text, and always its accessible name. */
   launcherLabel?: string;
+  /**
+   * Where the widget sits; see {@link ChatWidgetPlacement}. Defaults to
+   * `"bottom-right"`, floating clear of the device's safe-area insets. Stacks
+   * at `--clivly-chat-z-index` (default 2147483000) — lower it through
+   * `style` to sit beneath the host's own dialogs.
+   */
+  placement?: ChatWidgetPlacement;
   storage?: Pick<Storage, "getItem" | "setItem">;
   /**
    * Inline styles on the widget root. The intended use is overriding palette