@xbrain-swe/nova-chat-widget 0.1.8 → 0.1.10

package/dist/index.d.cts

@@ -24,6 +24,8 @@ type TextPart = {
 };
 type MessagePart = TextPart | ToolPart;
 type ChatMessage = {
+    /** assistant 메시지가 서버에 저장될 때의 id(`start` 청크의 `messageId`). 만족도 피드백 대상 식별용. */
+    id?: string;
     role: "user" | "assistant";
     parts: MessagePart[];
 };
@@ -109,6 +111,57 @@ declare function XbNovaProvider({ apiKey, botId, appId, screen, apiBaseUrl, clie
     children: React.ReactNode;
 }): react.JSX.Element;
 
+type ClientResults = Record<string, {
+    view: ViewKind;
+    output: unknown;
+}>;
+type XbNovaFeedbackRating = "up" | "down" | null;
+/** 👎 사유 칩의 코드. */
+type XbNovaFeedbackReason = "inaccurate" | "irrelevant" | "too_long" | "unclear";
+/** 답변 만족도 저장 성공 후 호스트로 전달되는 이벤트. `rating: null`은 평가 취소. */
+type XbNovaFeedbackEvent = {
+    conversationId: string;
+    messageId: string;
+    rating: XbNovaFeedbackRating;
+    /** 👎일 때 사용자가 고른 사유 코드(없으면 undefined). */
+    reason?: XbNovaFeedbackReason;
+};
+type XbNovaOnboarding = {
+    conversation_id: string;
+    greeting: string;
+    quick_replies: string[];
+    branding: {
+        title?: string;
+        logo_url?: string;
+        avatar_text?: string;
+    };
+};
+type UseXbNovaChatResult = {
+    onboarding: XbNovaOnboarding | null;
+    messages: ChatMessage[];
+    busy: boolean;
+    error: string | null;
+    send: (text: string) => Promise<void>;
+    /** client action 핸들러가 돌려준 정규화 결과(tool_call_id별). 채팅 화면이 view 렌더러로 그린다. */
+    clientResults: ClientResults;
+    /** messageId → 현재 평가. 평가 안 한 메시지는 키가 없다. */
+    feedback: Record<string, XbNovaFeedbackRating>;
+    /** 낙관적으로 반영하고 서버에 저장한다. 실패하면 되돌린다. */
+    setFeedback: (messageId: string, rating: XbNovaFeedbackRating, reason?: XbNovaFeedbackReason) => Promise<void>;
+};
+/** `botId`를 넘기면 Provider의 기본 봇 대신 그 봇으로 새 대화를 연다 — 넛지 handoff가 쓴다.
+ * `nudgeNodeId`를 넘기면 이 대화가 그 넛지에서 시작됐다고 서버에 표시한다 — 넛지 전환
+ * 퍼널(노출→클릭→첫질문→전환)의 마지막 단계가 이 값이 채워진 대화 수를 센다.
+ * `onDismissSheet`는 `dismissSheet: true`인 client action이 실행될 때 호출된다 —
+ * `<XbNovaChat>`이 시트를 닫는 함수를 넘겨준다(모바일에서 시트가 페이지 대부분을 덮어서,
+ * 안 닫으면 그 밑에서 일어나는 일이 안 보인다). */
+declare function useXbNovaChat(options?: {
+    botId?: string;
+    nudgeNodeId?: string;
+    onDismissSheet?: () => void;
+    onFeedback?: (e: XbNovaFeedbackEvent) => void;
+}): UseXbNovaChatResult;
+
 type ProductItem = {
     id: string;
     title: string;
@@ -148,7 +201,7 @@ type ViewRenderer = (props: {
 }) => React.ReactNode;
 type ViewRendererMap = Partial<Record<ViewKind, ViewRenderer>>;
 
-declare function XbNovaChat({ viewRenderers, botId, barStyle, panelStyle, backdropStyle, defaultOpen, idleText, avatarSize, onVerdictAction, }: {
+declare function XbNovaChat({ viewRenderers, botId, barStyle, panelStyle, backdropStyle, defaultOpen, idleText, avatarSize, onVerdictAction, feedback: feedbackEnabled, onFeedback, }: {
     /** 특정 view만 자체 컴포넌트로 덮어쓰고 싶을 때 — 지정 안 한 view는 기본 렌더러를 쓴다. */
     viewRenderers?: ViewRendererMap;
     /** Provider의 기본 봇 대신 다른 봇과 고정적으로 대화하고 싶을 때. 힌트를 눌러 열면
@@ -173,43 +226,12 @@ declare function XbNovaChat({ viewRenderers, botId, barStyle, panelStyle, backdr
     /** 판단 카드의 행동 버튼을 눌렀을 때 — 실제 동작(상담신청 폼 열기, 섹션 스크롤 등)은
      * 소비자가 정한다. SDK는 버튼에 적힌 `action` 문자열을 그대로 넘겨줄 뿐 뜻을 모른다. */
     onVerdictAction?: (action: string) => void;
+    /** 완료된 답변 아래 👍/👎 "상담 만족도" 버튼을 보일지. 기본 true. */
+    feedback?: boolean;
+    /** 만족도가 서버에 저장된 뒤 호출된다(분석 이벤트 전송용). `rating: null`은 평가 취소. */
+    onFeedback?: (e: XbNovaFeedbackEvent) => void;
 }): react.JSX.Element | null;
 
-type ClientResults = Record<string, {
-    view: ViewKind;
-    output: unknown;
-}>;
-type XbNovaOnboarding = {
-    conversation_id: string;
-    greeting: string;
-    quick_replies: string[];
-    branding: {
-        title?: string;
-        logo_url?: string;
-        avatar_text?: string;
-    };
-};
-type UseXbNovaChatResult = {
-    onboarding: XbNovaOnboarding | null;
-    messages: ChatMessage[];
-    busy: boolean;
-    error: string | null;
-    send: (text: string) => Promise<void>;
-    /** client action 핸들러가 돌려준 정규화 결과(tool_call_id별). 채팅 화면이 view 렌더러로 그린다. */
-    clientResults: ClientResults;
-};
-/** `botId`를 넘기면 Provider의 기본 봇 대신 그 봇으로 새 대화를 연다 — 넛지 handoff가 쓴다.
- * `nudgeNodeId`를 넘기면 이 대화가 그 넛지에서 시작됐다고 서버에 표시한다 — 넛지 전환
- * 퍼널(노출→클릭→첫질문→전환)의 마지막 단계가 이 값이 채워진 대화 수를 센다.
- * `onDismissSheet`는 `dismissSheet: true`인 client action이 실행될 때 호출된다 —
- * `<XbNovaChat>`이 시트를 닫는 함수를 넘겨준다(모바일에서 시트가 페이지 대부분을 덮어서,
- * 안 닫으면 그 밑에서 일어나는 일이 안 보인다). */
-declare function useXbNovaChat(options?: {
-    botId?: string;
-    nudgeNodeId?: string;
-    onDismissSheet?: () => void;
-}): UseXbNovaChatResult;
-
 /** ref형 — 감싸는 엘리먼트를 늘리기 싫을 때. `<div ref={useXbNovaTrack("price", data)}>`. */
 declare function useXbNovaTrack<T extends HTMLElement = HTMLElement>(region: string, data?: FactValue, label?: string): (node: T | null) => void;
 /** 선언형 — 감싸기만 하면 됨. `<XbNovaTrack region="price" data={{...}}>...</XbNovaTrack>`. */
@@ -252,4 +274,4 @@ declare function useXbNovaSettings(): {
     showBar: () => void;
 };
 
-export { type ChatMessage, type FactValue, type MessagePart, type ProductItem, type TextPart, type ToolPart, type UseXbNovaChatResult, type VerdictAction, type VerdictOutput, type ViewKind, type ViewRenderer, type ViewRendererMap, XbNovaChat, type XbNovaClientAction, type XbNovaClientActionResult, type XbNovaClientActions, XbNovaFact, XbNovaFacts, type XbNovaOnboarding, XbNovaProvider, type XbNovaTheme, XbNovaTrack, trackXbNovaEvent, useXbNovaChat, useXbNovaFact, useXbNovaFacts, useXbNovaSettings, useXbNovaTrack, useXbNovaVisitor };
+export { type ChatMessage, type FactValue, type MessagePart, type ProductItem, type TextPart, type ToolPart, type UseXbNovaChatResult, type VerdictAction, type VerdictOutput, type ViewKind, type ViewRenderer, type ViewRendererMap, XbNovaChat, type XbNovaClientAction, type XbNovaClientActionResult, type XbNovaClientActions, XbNovaFact, XbNovaFacts, type XbNovaFeedbackEvent, type XbNovaFeedbackRating, type XbNovaFeedbackReason, type XbNovaOnboarding, XbNovaProvider, type XbNovaTheme, XbNovaTrack, trackXbNovaEvent, useXbNovaChat, useXbNovaFact, useXbNovaFacts, useXbNovaSettings, useXbNovaTrack, useXbNovaVisitor };

package/dist/index.d.ts

@@ -24,6 +24,8 @@ type TextPart = {
 };
 type MessagePart = TextPart | ToolPart;
 type ChatMessage = {
+    /** assistant 메시지가 서버에 저장될 때의 id(`start` 청크의 `messageId`). 만족도 피드백 대상 식별용. */
+    id?: string;
     role: "user" | "assistant";
     parts: MessagePart[];
 };
@@ -109,6 +111,57 @@ declare function XbNovaProvider({ apiKey, botId, appId, screen, apiBaseUrl, clie
     children: React.ReactNode;
 }): react.JSX.Element;
 
+type ClientResults = Record<string, {
+    view: ViewKind;
+    output: unknown;
+}>;
+type XbNovaFeedbackRating = "up" | "down" | null;
+/** 👎 사유 칩의 코드. */
+type XbNovaFeedbackReason = "inaccurate" | "irrelevant" | "too_long" | "unclear";
+/** 답변 만족도 저장 성공 후 호스트로 전달되는 이벤트. `rating: null`은 평가 취소. */
+type XbNovaFeedbackEvent = {
+    conversationId: string;
+    messageId: string;
+    rating: XbNovaFeedbackRating;
+    /** 👎일 때 사용자가 고른 사유 코드(없으면 undefined). */
+    reason?: XbNovaFeedbackReason;
+};
+type XbNovaOnboarding = {
+    conversation_id: string;
+    greeting: string;
+    quick_replies: string[];
+    branding: {
+        title?: string;
+        logo_url?: string;
+        avatar_text?: string;
+    };
+};
+type UseXbNovaChatResult = {
+    onboarding: XbNovaOnboarding | null;
+    messages: ChatMessage[];
+    busy: boolean;
+    error: string | null;
+    send: (text: string) => Promise<void>;
+    /** client action 핸들러가 돌려준 정규화 결과(tool_call_id별). 채팅 화면이 view 렌더러로 그린다. */
+    clientResults: ClientResults;
+    /** messageId → 현재 평가. 평가 안 한 메시지는 키가 없다. */
+    feedback: Record<string, XbNovaFeedbackRating>;
+    /** 낙관적으로 반영하고 서버에 저장한다. 실패하면 되돌린다. */
+    setFeedback: (messageId: string, rating: XbNovaFeedbackRating, reason?: XbNovaFeedbackReason) => Promise<void>;
+};
+/** `botId`를 넘기면 Provider의 기본 봇 대신 그 봇으로 새 대화를 연다 — 넛지 handoff가 쓴다.
+ * `nudgeNodeId`를 넘기면 이 대화가 그 넛지에서 시작됐다고 서버에 표시한다 — 넛지 전환
+ * 퍼널(노출→클릭→첫질문→전환)의 마지막 단계가 이 값이 채워진 대화 수를 센다.
+ * `onDismissSheet`는 `dismissSheet: true`인 client action이 실행될 때 호출된다 —
+ * `<XbNovaChat>`이 시트를 닫는 함수를 넘겨준다(모바일에서 시트가 페이지 대부분을 덮어서,
+ * 안 닫으면 그 밑에서 일어나는 일이 안 보인다). */
+declare function useXbNovaChat(options?: {
+    botId?: string;
+    nudgeNodeId?: string;
+    onDismissSheet?: () => void;
+    onFeedback?: (e: XbNovaFeedbackEvent) => void;
+}): UseXbNovaChatResult;
+
 type ProductItem = {
     id: string;
     title: string;
@@ -148,7 +201,7 @@ type ViewRenderer = (props: {
 }) => React.ReactNode;
 type ViewRendererMap = Partial<Record<ViewKind, ViewRenderer>>;
 
-declare function XbNovaChat({ viewRenderers, botId, barStyle, panelStyle, backdropStyle, defaultOpen, idleText, avatarSize, onVerdictAction, }: {
+declare function XbNovaChat({ viewRenderers, botId, barStyle, panelStyle, backdropStyle, defaultOpen, idleText, avatarSize, onVerdictAction, feedback: feedbackEnabled, onFeedback, }: {
     /** 특정 view만 자체 컴포넌트로 덮어쓰고 싶을 때 — 지정 안 한 view는 기본 렌더러를 쓴다. */
     viewRenderers?: ViewRendererMap;
     /** Provider의 기본 봇 대신 다른 봇과 고정적으로 대화하고 싶을 때. 힌트를 눌러 열면
@@ -173,43 +226,12 @@ declare function XbNovaChat({ viewRenderers, botId, barStyle, panelStyle, backdr
     /** 판단 카드의 행동 버튼을 눌렀을 때 — 실제 동작(상담신청 폼 열기, 섹션 스크롤 등)은
      * 소비자가 정한다. SDK는 버튼에 적힌 `action` 문자열을 그대로 넘겨줄 뿐 뜻을 모른다. */
     onVerdictAction?: (action: string) => void;
+    /** 완료된 답변 아래 👍/👎 "상담 만족도" 버튼을 보일지. 기본 true. */
+    feedback?: boolean;
+    /** 만족도가 서버에 저장된 뒤 호출된다(분석 이벤트 전송용). `rating: null`은 평가 취소. */
+    onFeedback?: (e: XbNovaFeedbackEvent) => void;
 }): react.JSX.Element | null;
 
-type ClientResults = Record<string, {
-    view: ViewKind;
-    output: unknown;
-}>;
-type XbNovaOnboarding = {
-    conversation_id: string;
-    greeting: string;
-    quick_replies: string[];
-    branding: {
-        title?: string;
-        logo_url?: string;
-        avatar_text?: string;
-    };
-};
-type UseXbNovaChatResult = {
-    onboarding: XbNovaOnboarding | null;
-    messages: ChatMessage[];
-    busy: boolean;
-    error: string | null;
-    send: (text: string) => Promise<void>;
-    /** client action 핸들러가 돌려준 정규화 결과(tool_call_id별). 채팅 화면이 view 렌더러로 그린다. */
-    clientResults: ClientResults;
-};
-/** `botId`를 넘기면 Provider의 기본 봇 대신 그 봇으로 새 대화를 연다 — 넛지 handoff가 쓴다.
- * `nudgeNodeId`를 넘기면 이 대화가 그 넛지에서 시작됐다고 서버에 표시한다 — 넛지 전환
- * 퍼널(노출→클릭→첫질문→전환)의 마지막 단계가 이 값이 채워진 대화 수를 센다.
- * `onDismissSheet`는 `dismissSheet: true`인 client action이 실행될 때 호출된다 —
- * `<XbNovaChat>`이 시트를 닫는 함수를 넘겨준다(모바일에서 시트가 페이지 대부분을 덮어서,
- * 안 닫으면 그 밑에서 일어나는 일이 안 보인다). */
-declare function useXbNovaChat(options?: {
-    botId?: string;
-    nudgeNodeId?: string;
-    onDismissSheet?: () => void;
-}): UseXbNovaChatResult;
-
 /** ref형 — 감싸는 엘리먼트를 늘리기 싫을 때. `<div ref={useXbNovaTrack("price", data)}>`. */
 declare function useXbNovaTrack<T extends HTMLElement = HTMLElement>(region: string, data?: FactValue, label?: string): (node: T | null) => void;
 /** 선언형 — 감싸기만 하면 됨. `<XbNovaTrack region="price" data={{...}}>...</XbNovaTrack>`. */
@@ -252,4 +274,4 @@ declare function useXbNovaSettings(): {
     showBar: () => void;
 };
 
-export { type ChatMessage, type FactValue, type MessagePart, type ProductItem, type TextPart, type ToolPart, type UseXbNovaChatResult, type VerdictAction, type VerdictOutput, type ViewKind, type ViewRenderer, type ViewRendererMap, XbNovaChat, type XbNovaClientAction, type XbNovaClientActionResult, type XbNovaClientActions, XbNovaFact, XbNovaFacts, type XbNovaOnboarding, XbNovaProvider, type XbNovaTheme, XbNovaTrack, trackXbNovaEvent, useXbNovaChat, useXbNovaFact, useXbNovaFacts, useXbNovaSettings, useXbNovaTrack, useXbNovaVisitor };
+export { type ChatMessage, type FactValue, type MessagePart, type ProductItem, type TextPart, type ToolPart, type UseXbNovaChatResult, type VerdictAction, type VerdictOutput, type ViewKind, type ViewRenderer, type ViewRendererMap, XbNovaChat, type XbNovaClientAction, type XbNovaClientActionResult, type XbNovaClientActions, XbNovaFact, XbNovaFacts, type XbNovaFeedbackEvent, type XbNovaFeedbackRating, type XbNovaFeedbackReason, type XbNovaOnboarding, XbNovaProvider, type XbNovaTheme, XbNovaTrack, trackXbNovaEvent, useXbNovaChat, useXbNovaFact, useXbNovaFacts, useXbNovaSettings, useXbNovaTrack, useXbNovaVisitor };