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

package/dist/index.d.cts

@@ -80,6 +80,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}}>`로 자기 브랜드 컬러를
  * 넘기면 그걸 쓴다("카통령 브랜드 컬러를 따르게 해달라" — 파랑/보라가 사이트 톤과 안
@@ -158,6 +164,10 @@ type UseXbNovaChatResult = {
 declare function useXbNovaChat(options?: {
     botId?: string;
     nudgeNodeId?: string;
+    /** 위젯이 첫 말풍선으로 보여준 문구(넛지 문구). 첫 메시지를 보낼 때 서버에 같이 보내 AI가
+     * "방금 이런 말을 건넸다"는 걸 알게 한다 — 없으면 봇 인사말을 쓴다. 서버가 설정과 일치하는지
+     * 검증해서 맞는 것만 이력에 저장한다. */
+    openingMessage?: string;
     onDismissSheet?: () => void;
     onFeedback?: (e: XbNovaFeedbackEvent) => void;
 }): UseXbNovaChatResult;
@@ -249,6 +259,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 +289,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, XbNovaProvider, type XbNovaTheme, XbNovaTrack, trackXbNovaEvent, useXbNovaChat, useXbNovaContext, useXbNovaFact, useXbNovaFacts, useXbNovaSettings, useXbNovaTrack, useXbNovaVisitor };

package/dist/index.d.ts

@@ -80,6 +80,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}}>`로 자기 브랜드 컬러를
  * 넘기면 그걸 쓴다("카통령 브랜드 컬러를 따르게 해달라" — 파랑/보라가 사이트 톤과 안
@@ -158,6 +164,10 @@ type UseXbNovaChatResult = {
 declare function useXbNovaChat(options?: {
     botId?: string;
     nudgeNodeId?: string;
+    /** 위젯이 첫 말풍선으로 보여준 문구(넛지 문구). 첫 메시지를 보낼 때 서버에 같이 보내 AI가
+     * "방금 이런 말을 건넸다"는 걸 알게 한다 — 없으면 봇 인사말을 쓴다. 서버가 설정과 일치하는지
+     * 검증해서 맞는 것만 이력에 저장한다. */
+    openingMessage?: string;
     onDismissSheet?: () => void;
     onFeedback?: (e: XbNovaFeedbackEvent) => void;
 }): UseXbNovaChatResult;
@@ -249,6 +259,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 +289,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, XbNovaProvider, type XbNovaTheme, XbNovaTrack, trackXbNovaEvent, useXbNovaChat, useXbNovaContext, useXbNovaFact, useXbNovaFacts, useXbNovaSettings, useXbNovaTrack, useXbNovaVisitor };

package/dist/index.js

@@ -40,6 +40,17 @@ function resolveVisitorId() {
 function resolveFactValue(value) {
   return typeof value === "function" ? value() : value;
 }
+function collectContextEntries(registry) {
+  const out = [];
+  for (const source of registry.values()) {
+    const entries = typeof source === "function" ? source() : source;
+    if (!Array.isArray(entries)) continue;
+    for (const e of entries) {
+      if (e && typeof e.title === "string" && typeof e.description === "string") out.push(e);
+    }
+  }
+  return out;
+}
 function InternalProvider({
   auth,
   clientActionHandlers,
@@ -48,6 +59,7 @@ function InternalProvider({
 }) {
   const trackRegistry = useRef(/* @__PURE__ */ new Map()).current;
   const factsRegistry = useRef(/* @__PURE__ */ new Map()).current;
+  const contextRegistry = useRef(/* @__PURE__ */ new Map()).current;
   const emptyHandlers = useRef(/* @__PURE__ */ new Map()).current;
   const visitorIdRef = useRef(null);
   if (visitorIdRef.current === null) {
@@ -58,11 +70,12 @@ function InternalProvider({
       auth,
       trackRegistry,
       factsRegistry,
+      contextRegistry,
       clientActionHandlers: clientActionHandlers ?? emptyHandlers,
       visitorId: visitorIdRef.current,
       theme
     }),
-    [auth, trackRegistry, factsRegistry, clientActionHandlers, emptyHandlers, theme]
+    [auth, trackRegistry, factsRegistry, contextRegistry, clientActionHandlers, emptyHandlers, theme]
   );
   return /* @__PURE__ */ jsx(InternalContext.Provider, { value, children });
 }
@@ -1089,7 +1102,7 @@ async function resumeToolResult(apiBaseUrl, apiKey, body, handlers) {
 // src/use-chat.ts
 var DEFAULT_CLIENT_ACTION_TIMEOUT_MS = 15e3;
 function useXbNovaChat(options) {
-  const { auth, trackRegistry, clientActionHandlers, visitorId } = useXbNovaInternal();
+  const { auth, trackRegistry, contextRegistry, clientActionHandlers, visitorId } = useXbNovaInternal();
   const botId = options?.botId ?? auth.botId;
   const nudgeNodeId = options?.nudgeNodeId;
   const { apiKey, apiBaseUrl } = auth;
@@ -1241,7 +1254,9 @@ function useXbNovaChat(options) {
       return next;
     });
     const focused = getFocusedTrackEntry(trackRegistry);
-    const context = focused ? { region: focused.region, data: resolveFactValue(focused.data) } : void 0;
+    const notes = collectContextEntries(contextRegistry);
+    const screen = focused ? { region: focused.region, data: resolveFactValue(focused.data) } : {};
+    const context = focused || notes.length ? { ...screen, ...notes.length ? { notes } : {} } : void 0;
     try {
       await streamChat(
         apiBaseUrl,
@@ -1251,7 +1266,8 @@ function useXbNovaChat(options) {
           message: trimmed,
           conversation_id: onboarding?.conversation_id ?? null,
           context,
-          nudge_node_id: nudgeNodeId ?? null
+          nudge_node_id: nudgeNodeId ?? null,
+          opening_message: messages.length === 0 ? (options?.openingMessage ?? onboarding?.greeting) || null : null
         },
         { onPart: replaceLast, onMessageId: setLastAssistantId, onError: setError }
       );
@@ -1550,6 +1566,7 @@ function XbNovaChat({
     onFeedback,
     botId: activeBotId ?? botId,
     nudgeNodeId: activeNudgeNodeId,
+    openingMessage: openingLine ?? void 0,
     onDismissSheet: () => setOpen(false)
   });
   const effectiveBotId = activeBotId ?? botId;
@@ -2124,7 +2141,7 @@ function AnswerActionsFrame({
 }
 
 // src/facts.ts
-import { useEffect as useEffect9, useRef as useRef9 } from "react";
+import { useEffect as useEffect9, useId, useRef as useRef9 } from "react";
 function useXbNovaFact(key, value) {
   const { factsRegistry } = useXbNovaInternal();
   useEffect9(() => {
@@ -2153,6 +2170,18 @@ function useXbNovaFacts(values) {
     };
   }, [factsRegistry]);
 }
+function useXbNovaContext(entries) {
+  const { contextRegistry } = useXbNovaInternal();
+  const id = useId();
+  useEffect9(() => {
+    contextRegistry.set(id, entries);
+  });
+  useEffect9(() => {
+    return () => {
+      contextRegistry.delete(id);
+    };
+  }, [id, contextRegistry]);
+}
 function useXbNovaVisitor() {
   const { visitorId } = useXbNovaInternal();
   return visitorId;
@@ -2173,6 +2202,7 @@ export {
   XbNovaTrack,
   trackXbNovaEvent,
   useXbNovaChat,
+  useXbNovaContext,
   useXbNovaFact,
   useXbNovaFacts,
   useXbNovaSettings,