@xbrain-swe/nova-chat-widget 0.1.10 → 0.2.4-dev.15

package/dist/index.d.cts

@@ -29,6 +29,13 @@ type ChatMessage = {
     role: "user" | "assistant";
     parts: MessagePart[];
 };
+/** 서버에 저장된 메시지(`parts`는 AI SDK UIMessage.parts 원본) — 이어 연 대화의 이력. */
+type StoredMessage = {
+    id: string;
+    role: "user" | "assistant";
+    sender?: string;
+    parts: Record<string, unknown>[];
+};
 
 /** `awaitResult` 핸들러가 구조화된 결과를 돌려줄 때의 모양. `text`는 모델이 읽는 결과(서버로
  * 전송)고, `view`+`output`은 채팅 말풍선에 직접 그릴 정규화된 데이터다 — 서버에는 가지 않는다.
@@ -80,6 +87,12 @@ type XbNovaClientAction = {
 type XbNovaClientActions = Record<string, XbNovaClientAction>;
 
 type FactValue = unknown | (() => unknown);
+/** `useXbNovaContext`로 호스트가 AI에게 알려주는 상품·화면 부가 설명 한 건. 내용은 전부
+ * 호스트 자율이다 — 가입 됨/안됨 같은 판단도 호스트가 `description`에 문장으로 쓴다. */
+type XbNovaContextEntry = {
+    title: string;
+    description: string;
+};
 /** 위젯 아바타·pill 배경 그라디언트에 쓰는 두 색상 — 기본값은 SDK 자체 톤(인디고→바이올렛)
  * 이고, 소비자가 `<XbNovaProvider theme={{accentFrom, accentTo}}>`로 자기 브랜드 컬러를
  * 넘기면 그걸 쓴다("카통령 브랜드 컬러를 따르게 해달라" — 파랑/보라가 사이트 톤과 안
@@ -94,12 +107,22 @@ type XbNovaTheme = {
     colorScheme: "light" | "dark" | "system";
 };
 
-declare function XbNovaProvider({ apiKey, botId, appId, screen, apiBaseUrl, clientActions, theme, children, }: {
+declare function XbNovaProvider({ apiKey, botId, appId, screen, apiBaseUrl, clientActions, theme, userKey, threadKey, sessionKey, children, }: {
     apiKey: string;
     botId: string;
     appId: string;
     screen?: string;
     apiBaseUrl?: string;
+    /** 이 방문자를 가리키는 호스트 쪽 키(예: GA4 user_pseudo_id). nova가 남기는 방문자 ID(대화·넛지
+     * 이벤트·피드백) 전부가 이 값이 되고, `threadKey`와 함께 이전 대화를 찾는 데도 쓴다. 공개 키로 조회하므로 추측하기 어려운 값이어야 한다 — 회원 ID를 그대로
+     * 넘기지 않는다. 안 주면 SDK가 브라우저에 만들어 둔 `visitorId`를 쓴다. */
+    userKey?: string;
+    /** 대화를 이어 붙일 단위(예: `vehicle:${매물ID}`). 같은 유저 키·스레드 키로 위젯이 다시 열리면
+     * 이전 대화와 이력을 복원한다. 안 주면 열 때마다 새 대화다. */
+    threadKey?: string;
+    /** 이 방문의 세션 키(예: GA4 session_id). nova가 남기는 이벤트(위젯 노출·넛지·상담 버튼)와 대화에 실려
+     * 콘솔에서 세션 단위로 집계된다. 값이 바뀌면(세션 갱신) 그 뒤 이벤트부터 새 값으로 실린다. 안 주면 세션은 비운다. */
+    sessionKey?: string;
     /** 이 페이지가 AI에게 내어줄 client action tool — 이름별로 설명·스키마·실행 함수를
      * 등록한다("SDK 초기화 시점에 등록"). 스펙은 App 레벨 레지스트리로 자동 동기화되고
      * (`XbNovaClientActionSync`), 콘솔의 tool 목록에 반영된다. 핸들러는 여기서만 산다. */
@@ -127,17 +150,24 @@ type XbNovaFeedbackEvent = {
     reason?: XbNovaFeedbackReason;
 };
 type XbNovaOnboarding = {
-    conversation_id: string;
+    /** 이어 열 대화가 없으면 null — 첫 메시지를 보낼 때 서버가 만든다(지연 생성). */
+    conversation_id: string | null;
+    /** 이어 연 대화의 이력. 새 대화면 빈 배열. */
+    messages?: StoredMessage[];
     greeting: string;
     quick_replies: string[];
     branding: {
         title?: string;
         logo_url?: string;
         avatar_text?: string;
+        badge_text?: string;
+        disclaimer?: string;
     };
 };
 type UseXbNovaChatResult = {
     onboarding: XbNovaOnboarding | null;
+    /** 대화 맨 위에 그릴 첫 말풍선(넛지 문구·인사말). 이어 연 대화면 이력에 이미 있으니 null. */
+    opening: string | null;
     messages: ChatMessage[];
     busy: boolean;
     error: string | null;
@@ -148,16 +178,22 @@ type UseXbNovaChatResult = {
     feedback: Record<string, XbNovaFeedbackRating>;
     /** 낙관적으로 반영하고 서버에 저장한다. 실패하면 되돌린다. */
     setFeedback: (messageId: string, rating: XbNovaFeedbackRating, reason?: XbNovaFeedbackReason) => Promise<void>;
+    /** client action이 그린 버튼(상담신청 등)이 눌렸을 때 채팅 화면이 부른다 — nova 넛지 퍼널의 마지막 단계. */
+    trackClientActionClick: (action: string, label: string | null) => void;
 };
 /** `botId`를 넘기면 Provider의 기본 봇 대신 그 봇으로 새 대화를 연다 — 넛지 handoff가 쓴다.
  * `nudgeNodeId`를 넘기면 이 대화가 그 넛지에서 시작됐다고 서버에 표시한다 — 넛지 전환
- * 퍼널(노출→클릭→첫질문→전환)의 마지막 단계가 이 값이 채워진 대화 수를 센다.
+ * 퍼널(노출→클릭→첫 질문→상담 버튼 노출→클릭)이 이 값이 채워진 대화를 넛지 대화로 본다.
  * `onDismissSheet`는 `dismissSheet: true`인 client action이 실행될 때 호출된다 —
  * `<XbNovaChat>`이 시트를 닫는 함수를 넘겨준다(모바일에서 시트가 페이지 대부분을 덮어서,
  * 안 닫으면 그 밑에서 일어나는 일이 안 보인다). */
 declare function useXbNovaChat(options?: {
     botId?: string;
     nudgeNodeId?: string;
+    /** 위젯이 첫 말풍선으로 보여준 문구(넛지 문구). 첫 메시지를 보낼 때 서버에 같이 보내 AI가
+     * "방금 이런 말을 건넸다"는 걸 알게 한다 — 없으면 봇 인사말을 쓴다. 서버가 설정과 일치하는지
+     * 검증해서 맞는 것만 이력에 저장한다. */
+    openingMessage?: string;
     onDismissSheet?: () => void;
     onFeedback?: (e: XbNovaFeedbackEvent) => void;
 }): UseXbNovaChatResult;
@@ -201,7 +237,14 @@ type ViewRenderer = (props: {
 }) => React.ReactNode;
 type ViewRendererMap = Partial<Record<ViewKind, ViewRenderer>>;
 
-declare function XbNovaChat({ viewRenderers, botId, barStyle, panelStyle, backdropStyle, defaultOpen, idleText, avatarSize, onVerdictAction, feedback: feedbackEnabled, onFeedback, }: {
+/** 바(AI 버튼)를 눌러 대화 시트를 열 때 `onOpen`으로 넘어오는 값. */
+type XbNovaOpenEvent = {
+    /** 넛지 힌트 맥락으로 열었는지 — 힌트가 떠 있었거나, 방금 조용히 소멸한 힌트를 이어 열었으면 true. */
+    fromNudge: boolean;
+    /** `fromNudge`일 때 그 힌트 문구. */
+    hintText?: string;
+};
+declare function XbNovaChat({ viewRenderers, botId, barStyle, panelStyle, backdropStyle, defaultOpen, idleText, avatarSize, onVerdictAction, feedback: feedbackEnabled, onFeedback, onOpen, }: {
     /** 특정 view만 자체 컴포넌트로 덮어쓰고 싶을 때 — 지정 안 한 view는 기본 렌더러를 쓴다. */
     viewRenderers?: ViewRendererMap;
     /** Provider의 기본 봇 대신 다른 봇과 고정적으로 대화하고 싶을 때. 힌트를 눌러 열면
@@ -230,6 +273,10 @@ declare function XbNovaChat({ viewRenderers, botId, barStyle, panelStyle, backdr
     feedback?: boolean;
     /** 만족도가 서버에 저장된 뒤 호출된다(분석 이벤트 전송용). `rating: null`은 평가 취소. */
     onFeedback?: (e: XbNovaFeedbackEvent) => void;
+    /** 바를 눌러 대화 시트를 열 때 호출된다(분석 이벤트 전송용). 클릭이 Shadow DOM 안에서
+     * 일어나 호스트가 직접 잡을 수 없어서 여는 콜백이다. `defaultOpen`으로 처음부터 열린 경우엔
+     * 호출되지 않는다. */
+    onOpen?: (e: XbNovaOpenEvent) => void;
 }): react.JSX.Element | null;
 
 /** ref형 — 감싸는 엘리먼트를 늘리기 싫을 때. `<div ref={useXbNovaTrack("price", data)}>`. */
@@ -249,6 +296,11 @@ declare function useXbNovaFact(key: string, value: FactValue): void;
 /** 필드가 여러 개인 객체 하나를 한 번에 등록한다 — 매물 데이터처럼. `useXbNovaFact`를
  * 필드마다 반복하는 것과 같다. */
 declare function useXbNovaFacts(values: Record<string, FactValue>): void;
+/** AI에게 알려줄 상품·화면 부가 설명을 등록한다. 넛지 조건용인 facts와 달리 **챗 요청의
+ * `context`로 전송**되어 답변의 근거가 된다. 내용(가입 가능 여부 같은 판단 포함)은 호스트가
+ * `description`에 문장으로 쓴다 — SDK는 형식 검증과 전달만 한다. 배열 또는 함수(pull) 둘 다
+ * 된다. 컴포넌트가 언마운트되면 자동으로 빠진다. */
+declare function useXbNovaContext(entries: XbNovaContextEntry[] | (() => XbNovaContextEntry[])): void;
 /** 방문자 식별자 — 없으면 SDK가 즉시 만들어 localStorage에 고정한 뒤 그 값을 반환한다. */
 declare function useXbNovaVisitor(): string;
 /** 선언형 — 서버 컴포넌트 트리에서 훅을 못 쓸 때. `<XbNovaFact id="xbnova_summary" value="..." />`. */
@@ -274,4 +326,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 XbNovaFeedbackEvent, type XbNovaFeedbackRating, type XbNovaFeedbackReason, 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, type XbNovaContextEntry, XbNovaFact, XbNovaFacts, type XbNovaFeedbackEvent, type XbNovaFeedbackRating, type XbNovaFeedbackReason, type XbNovaOnboarding, type XbNovaOpenEvent, XbNovaProvider, type XbNovaTheme, XbNovaTrack, trackXbNovaEvent, useXbNovaChat, useXbNovaContext, useXbNovaFact, useXbNovaFacts, useXbNovaSettings, useXbNovaTrack, useXbNovaVisitor };

package/dist/index.d.ts

@@ -29,6 +29,13 @@ type ChatMessage = {
     role: "user" | "assistant";
     parts: MessagePart[];
 };
+/** 서버에 저장된 메시지(`parts`는 AI SDK UIMessage.parts 원본) — 이어 연 대화의 이력. */
+type StoredMessage = {
+    id: string;
+    role: "user" | "assistant";
+    sender?: string;
+    parts: Record<string, unknown>[];
+};
 
 /** `awaitResult` 핸들러가 구조화된 결과를 돌려줄 때의 모양. `text`는 모델이 읽는 결과(서버로
  * 전송)고, `view`+`output`은 채팅 말풍선에 직접 그릴 정규화된 데이터다 — 서버에는 가지 않는다.
@@ -80,6 +87,12 @@ type XbNovaClientAction = {
 type XbNovaClientActions = Record<string, XbNovaClientAction>;
 
 type FactValue = unknown | (() => unknown);
+/** `useXbNovaContext`로 호스트가 AI에게 알려주는 상품·화면 부가 설명 한 건. 내용은 전부
+ * 호스트 자율이다 — 가입 됨/안됨 같은 판단도 호스트가 `description`에 문장으로 쓴다. */
+type XbNovaContextEntry = {
+    title: string;
+    description: string;
+};
 /** 위젯 아바타·pill 배경 그라디언트에 쓰는 두 색상 — 기본값은 SDK 자체 톤(인디고→바이올렛)
  * 이고, 소비자가 `<XbNovaProvider theme={{accentFrom, accentTo}}>`로 자기 브랜드 컬러를
  * 넘기면 그걸 쓴다("카통령 브랜드 컬러를 따르게 해달라" — 파랑/보라가 사이트 톤과 안
@@ -94,12 +107,22 @@ type XbNovaTheme = {
     colorScheme: "light" | "dark" | "system";
 };
 
-declare function XbNovaProvider({ apiKey, botId, appId, screen, apiBaseUrl, clientActions, theme, children, }: {
+declare function XbNovaProvider({ apiKey, botId, appId, screen, apiBaseUrl, clientActions, theme, userKey, threadKey, sessionKey, children, }: {
     apiKey: string;
     botId: string;
     appId: string;
     screen?: string;
     apiBaseUrl?: string;
+    /** 이 방문자를 가리키는 호스트 쪽 키(예: GA4 user_pseudo_id). nova가 남기는 방문자 ID(대화·넛지
+     * 이벤트·피드백) 전부가 이 값이 되고, `threadKey`와 함께 이전 대화를 찾는 데도 쓴다. 공개 키로 조회하므로 추측하기 어려운 값이어야 한다 — 회원 ID를 그대로
+     * 넘기지 않는다. 안 주면 SDK가 브라우저에 만들어 둔 `visitorId`를 쓴다. */
+    userKey?: string;
+    /** 대화를 이어 붙일 단위(예: `vehicle:${매물ID}`). 같은 유저 키·스레드 키로 위젯이 다시 열리면
+     * 이전 대화와 이력을 복원한다. 안 주면 열 때마다 새 대화다. */
+    threadKey?: string;
+    /** 이 방문의 세션 키(예: GA4 session_id). nova가 남기는 이벤트(위젯 노출·넛지·상담 버튼)와 대화에 실려
+     * 콘솔에서 세션 단위로 집계된다. 값이 바뀌면(세션 갱신) 그 뒤 이벤트부터 새 값으로 실린다. 안 주면 세션은 비운다. */
+    sessionKey?: string;
     /** 이 페이지가 AI에게 내어줄 client action tool — 이름별로 설명·스키마·실행 함수를
      * 등록한다("SDK 초기화 시점에 등록"). 스펙은 App 레벨 레지스트리로 자동 동기화되고
      * (`XbNovaClientActionSync`), 콘솔의 tool 목록에 반영된다. 핸들러는 여기서만 산다. */
@@ -127,17 +150,24 @@ type XbNovaFeedbackEvent = {
     reason?: XbNovaFeedbackReason;
 };
 type XbNovaOnboarding = {
-    conversation_id: string;
+    /** 이어 열 대화가 없으면 null — 첫 메시지를 보낼 때 서버가 만든다(지연 생성). */
+    conversation_id: string | null;
+    /** 이어 연 대화의 이력. 새 대화면 빈 배열. */
+    messages?: StoredMessage[];
     greeting: string;
     quick_replies: string[];
     branding: {
         title?: string;
         logo_url?: string;
         avatar_text?: string;
+        badge_text?: string;
+        disclaimer?: string;
     };
 };
 type UseXbNovaChatResult = {
     onboarding: XbNovaOnboarding | null;
+    /** 대화 맨 위에 그릴 첫 말풍선(넛지 문구·인사말). 이어 연 대화면 이력에 이미 있으니 null. */
+    opening: string | null;
     messages: ChatMessage[];
     busy: boolean;
     error: string | null;
@@ -148,16 +178,22 @@ type UseXbNovaChatResult = {
     feedback: Record<string, XbNovaFeedbackRating>;
     /** 낙관적으로 반영하고 서버에 저장한다. 실패하면 되돌린다. */
     setFeedback: (messageId: string, rating: XbNovaFeedbackRating, reason?: XbNovaFeedbackReason) => Promise<void>;
+    /** client action이 그린 버튼(상담신청 등)이 눌렸을 때 채팅 화면이 부른다 — nova 넛지 퍼널의 마지막 단계. */
+    trackClientActionClick: (action: string, label: string | null) => void;
 };
 /** `botId`를 넘기면 Provider의 기본 봇 대신 그 봇으로 새 대화를 연다 — 넛지 handoff가 쓴다.
  * `nudgeNodeId`를 넘기면 이 대화가 그 넛지에서 시작됐다고 서버에 표시한다 — 넛지 전환
- * 퍼널(노출→클릭→첫질문→전환)의 마지막 단계가 이 값이 채워진 대화 수를 센다.
+ * 퍼널(노출→클릭→첫 질문→상담 버튼 노출→클릭)이 이 값이 채워진 대화를 넛지 대화로 본다.
  * `onDismissSheet`는 `dismissSheet: true`인 client action이 실행될 때 호출된다 —
  * `<XbNovaChat>`이 시트를 닫는 함수를 넘겨준다(모바일에서 시트가 페이지 대부분을 덮어서,
  * 안 닫으면 그 밑에서 일어나는 일이 안 보인다). */
 declare function useXbNovaChat(options?: {
     botId?: string;
     nudgeNodeId?: string;
+    /** 위젯이 첫 말풍선으로 보여준 문구(넛지 문구). 첫 메시지를 보낼 때 서버에 같이 보내 AI가
+     * "방금 이런 말을 건넸다"는 걸 알게 한다 — 없으면 봇 인사말을 쓴다. 서버가 설정과 일치하는지
+     * 검증해서 맞는 것만 이력에 저장한다. */
+    openingMessage?: string;
     onDismissSheet?: () => void;
     onFeedback?: (e: XbNovaFeedbackEvent) => void;
 }): UseXbNovaChatResult;
@@ -201,7 +237,14 @@ type ViewRenderer = (props: {
 }) => React.ReactNode;
 type ViewRendererMap = Partial<Record<ViewKind, ViewRenderer>>;
 
-declare function XbNovaChat({ viewRenderers, botId, barStyle, panelStyle, backdropStyle, defaultOpen, idleText, avatarSize, onVerdictAction, feedback: feedbackEnabled, onFeedback, }: {
+/** 바(AI 버튼)를 눌러 대화 시트를 열 때 `onOpen`으로 넘어오는 값. */
+type XbNovaOpenEvent = {
+    /** 넛지 힌트 맥락으로 열었는지 — 힌트가 떠 있었거나, 방금 조용히 소멸한 힌트를 이어 열었으면 true. */
+    fromNudge: boolean;
+    /** `fromNudge`일 때 그 힌트 문구. */
+    hintText?: string;
+};
+declare function XbNovaChat({ viewRenderers, botId, barStyle, panelStyle, backdropStyle, defaultOpen, idleText, avatarSize, onVerdictAction, feedback: feedbackEnabled, onFeedback, onOpen, }: {
     /** 특정 view만 자체 컴포넌트로 덮어쓰고 싶을 때 — 지정 안 한 view는 기본 렌더러를 쓴다. */
     viewRenderers?: ViewRendererMap;
     /** Provider의 기본 봇 대신 다른 봇과 고정적으로 대화하고 싶을 때. 힌트를 눌러 열면
@@ -230,6 +273,10 @@ declare function XbNovaChat({ viewRenderers, botId, barStyle, panelStyle, backdr
     feedback?: boolean;
     /** 만족도가 서버에 저장된 뒤 호출된다(분석 이벤트 전송용). `rating: null`은 평가 취소. */
     onFeedback?: (e: XbNovaFeedbackEvent) => void;
+    /** 바를 눌러 대화 시트를 열 때 호출된다(분석 이벤트 전송용). 클릭이 Shadow DOM 안에서
+     * 일어나 호스트가 직접 잡을 수 없어서 여는 콜백이다. `defaultOpen`으로 처음부터 열린 경우엔
+     * 호출되지 않는다. */
+    onOpen?: (e: XbNovaOpenEvent) => void;
 }): react.JSX.Element | null;
 
 /** ref형 — 감싸는 엘리먼트를 늘리기 싫을 때. `<div ref={useXbNovaTrack("price", data)}>`. */
@@ -249,6 +296,11 @@ declare function useXbNovaFact(key: string, value: FactValue): void;
 /** 필드가 여러 개인 객체 하나를 한 번에 등록한다 — 매물 데이터처럼. `useXbNovaFact`를
  * 필드마다 반복하는 것과 같다. */
 declare function useXbNovaFacts(values: Record<string, FactValue>): void;
+/** AI에게 알려줄 상품·화면 부가 설명을 등록한다. 넛지 조건용인 facts와 달리 **챗 요청의
+ * `context`로 전송**되어 답변의 근거가 된다. 내용(가입 가능 여부 같은 판단 포함)은 호스트가
+ * `description`에 문장으로 쓴다 — SDK는 형식 검증과 전달만 한다. 배열 또는 함수(pull) 둘 다
+ * 된다. 컴포넌트가 언마운트되면 자동으로 빠진다. */
+declare function useXbNovaContext(entries: XbNovaContextEntry[] | (() => XbNovaContextEntry[])): void;
 /** 방문자 식별자 — 없으면 SDK가 즉시 만들어 localStorage에 고정한 뒤 그 값을 반환한다. */
 declare function useXbNovaVisitor(): string;
 /** 선언형 — 서버 컴포넌트 트리에서 훅을 못 쓸 때. `<XbNovaFact id="xbnova_summary" value="..." />`. */
@@ -274,4 +326,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 XbNovaFeedbackEvent, type XbNovaFeedbackRating, type XbNovaFeedbackReason, 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, type XbNovaContextEntry, XbNovaFact, XbNovaFacts, type XbNovaFeedbackEvent, type XbNovaFeedbackRating, type XbNovaFeedbackReason, type XbNovaOnboarding, type XbNovaOpenEvent, XbNovaProvider, type XbNovaTheme, XbNovaTrack, trackXbNovaEvent, useXbNovaChat, useXbNovaContext, useXbNovaFact, useXbNovaFacts, useXbNovaSettings, useXbNovaTrack, useXbNovaVisitor };