@fcg-labs/cx-agent-hook 0.1.1 → 0.1.2

package/astro.d.ts

@@ -11,6 +11,7 @@ export declare function setupCxAiSuggest(
   options?: {
     hook?: CxHook;
     inquiry?: string;
+    context?: Record<string, string> | null;
     onAdopt?: (text: string, answerId: number | string | null) => void;
   },
 ): () => void;

package/astro.js

@@ -43,11 +43,14 @@ export { aiSuggestView } from "./view.js";
  *
  * @returns {() => void} 구독 해제
  */
-export function setupCxAiSuggest(element, { hook, inquiry = "", onAdopt } = {}) {
+export function setupCxAiSuggest(
+  element, { hook, inquiry = "", context = null, onAdopt } = {},
+) {
   defineCxAiSuggest();
   if (!element) return () => {};
   element.hook = hook;
   element.inquiry = inquiry;
+  element.context = context;
   if (!onAdopt) return () => {};
   const handler = (event) => onAdopt(event.detail.text, event.detail.answerId);
   element.addEventListener("cx-adopt", handler);

package/client.d.ts

@@ -56,7 +56,10 @@ export interface FeedbackInput {
 
 export declare class CxAgentClient {
   constructor(config: CxAgentConfig);
-  getAnswer(inquiry: string): Promise<AnswerResult>;
+  getAnswer(
+    inquiry: string,
+    context?: Record<string, string>,
+  ): Promise<AnswerResult>;
   sendFeedback(fb: FeedbackInput): Promise<FeedbackResult>;
   sent(answerId: number | string, finalText: string, agent?: string): Promise<FeedbackResult>;
   scored(answerId: number | string, score: number, agent?: string): Promise<FeedbackResult>;

package/client.js

@@ -41,6 +41,24 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+/**
+ * 고객 상황 맵 정규화 — 값 문자열 강제, 빈 값 제거. 실을 것이 없으면 null.
+ *
+ * 어휘 판단(어떤 키가 프롬프트에 실리나)은 SDK 의 몫이 아니다 — 서버의
+ * serving_context 가 정본이고, 여기는 "문자열 맵" 이라는 모양만 보장한다.
+ */
+function normalizeContext(context) {
+  if (!context || typeof context !== "object") return null;
+  const out = {};
+  for (const [key, value] of Object.entries(context)) {
+    if (value === null || value === undefined) continue;
+    const v = String(value).trim();
+    if (!v) continue;
+    out[String(key)] = v;
+  }
+  return Object.keys(out).length ? out : null;
+}
+
 export class CxAgentClient {
   /**
    * @param {object} config
@@ -141,10 +159,13 @@ export class CxAgentClient {
   /**
    * 서빙 답변 요청. throw 하지 않는다 — ok 로 판별.
    * @param {string} inquiry 고객 문의 원문
+   * @param {Record<string,string>} [context] 문의에 붙는 고객 상황 —
+   *   기기·앱 버전·문의 유형 같은 접지 신호와 융합 키(user_id 등).
+   *   값은 문자열로 강제되고, 비면 키 자체를 싣지 않는다(역호환).
    * @returns {Promise<{ok:boolean, answered:boolean, answer:string,
    *   answerId:number|null, evidence:Array, declinedReason:string, raw:object}>}
    */
-  async getAnswer(inquiry) {
+  async getAnswer(inquiry, context) {
     const target = this._target("answer");
     if (!target.path) {
       // throw 하지 않는다 — 이 SDK 의 원칙은 "CS팀 업무를 절대 막지 않는다".
@@ -159,8 +180,11 @@ export class CxAgentClient {
       };
     }
     try {
+      const body = { inquiry };
+      const ctx = normalizeContext(context);
+      if (ctx) body.context = ctx;
       const { status, data } = await this._post(
-        target.path(this.domain), { inquiry }, target,
+        target.path(this.domain), body, target,
       );
       if (status !== 200) {
         // 서버가 준 사유를 그대로 옮긴다. `http_503` 으로 뭉개면 "아직 안 켬"

package/element.d.ts

@@ -9,6 +9,8 @@ export declare const TAG: "cx-ai-suggest";
 export interface CxAiSuggestElement extends HTMLElement {
   hook: CxHook | null;
   inquiry: string;
+  /** 고객 상황 — 문의 리셋과 무관하게 최신값만 쓴다 */
+  context: Record<string, string> | null;
 }
 
 /** 커스텀 엘리먼트 등록. 두 번 불러도 안전하고, 브라우저가 아니면 무동작(false). */

package/element.js

@@ -45,6 +45,7 @@ function createClass() {
   return class CxAiSuggestElement extends HTMLElement {
     #hook = null;
     #inquiry = "";
+    #context = null;
     #state = "idle";
     #result = null;
 
@@ -52,6 +53,12 @@ function createClass() {
     get hook() { return this.#hook; }
     set hook(value) { this.#hook = value; this.#render(); }
 
+    /** 고객 상황 — 기기·버전·융합 키. 문의 리셋과 무관하게 최신값만 쓴다. */
+    get context() { return this.#context; }
+    set context(value) {
+      this.#context = value && typeof value === "object" ? value : null;
+    }
+
     /** 대상 문의 원문 */
     get inquiry() { return this.#inquiry; }
     set inquiry(value) {
@@ -73,7 +80,9 @@ function createClass() {
       if (!this.#inquiry || this.#state === "loading") return;
       this.#state = "loading";
       this.#render();
-      this.#result = await this.#hook.requestAnswer(this.#inquiry);
+      this.#result = await this.#hook.requestAnswer(
+        this.#inquiry, this.#context || undefined,
+      );
       this.#state = "done";
       this.#render();
     }

package/index.d.ts

@@ -37,7 +37,10 @@ export interface CxHook {
   /** 사유 코드 → 이 훅의 언어로 된 평문 */
   declineText(reason: string): string;
 
-  requestAnswer(inquiry: string): Promise<AnswerResult>;
+  requestAnswer(
+    inquiry: string,
+    context?: Record<string, string>,
+  ): Promise<AnswerResult>;
 
   /** 제안을 에디터에 넣었다 (패널이 부른다) */
   noteAdopted(answerId: number | string | null): void;

package/index.js

@@ -98,10 +98,11 @@ export function createCxHook(config = {}) {
       return textOf(messages, reason);
     },
 
-    /** 답변 제안 요청 — throw 하지 않음 */
-    requestAnswer(inquiry) {
+    /** 답변 제안 요청 — throw 하지 않음.
+     * context: 문의에 붙는 고객 상황(기기·버전·융합 키) — 선택. */
+    requestAnswer(inquiry, context) {
       if (!client || !inquiry) return Promise.resolve(NOT_CONFIGURED);
-      return client.getAnswer(inquiry);
+      return client.getAnswer(inquiry, context);
     },
 
     /** 제안을 에디터에 넣었다 (패널이 부른다) */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fcg-labs/cx-agent-hook",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "FCG CX Agent 후킹 SDK — 서빙 답변 수신 + CS팀 교정(점수·수정·발송) 후킹. 의존성 0, CMS에 install만으로 이식",
   "type": "module",
   "main": "index.js",

package/react.d.ts

@@ -7,6 +7,8 @@ export type { AiSuggestView } from "./view.js";
 export interface AiSuggestPanelProps {
   hook: CxHook;
   inquiry: string | undefined | null;
+  /** 고객 상황 — 요청 시점 최신값 사용 (리셋 deps 아님) */
+  context?: Record<string, string> | null;
   onAdopt?: (text: string) => void;
   /** 바깥 배치용 (레이아웃만 — 색·간격은 styles.css 변수로) */
   className?: string;

package/react.js

@@ -17,7 +17,7 @@
  * 단계가 없고(의존성 0 이 설계 성질), JSX 를 그대로 배포하면 소비처 번들러가
  * node_modules 를 변환해 주기를 기대해야 한다. createElement 로 직접 쓴다.
  */
-import { createElement as h, useCallback, useEffect, useState } from "react";
+import { createElement as h, useCallback, useEffect, useRef, useState } from "react";
 
 import { aiSuggestView, CLS } from "./view.js";
 
@@ -28,10 +28,13 @@ export { aiSuggestView };
  * @param {object}   props
  * @param {object}   props.hook      createCxHook() 결과
  * @param {string}   props.inquiry   대상 문의 원문
+ * @param {Record<string,string>} [props.context] 고객 상황 — 기기·버전·융합 키.
+ *   요청 시점의 최신 값을 쓴다. **리셋 deps 에 넣지 않는다** — 인라인 객체를
+ *   넘기면 리렌더마다 제안·채택 상태가 초기화된다.
  * @param {(text: string) => void} props.onAdopt  "에디터에 넣기"
  * @param {string}  [props.className] 바깥 배치용 (레이아웃만)
  */
-export function AiSuggestPanel({ hook, inquiry, onAdopt, className }) {
+export function AiSuggestPanel({ hook, inquiry, context, onAdopt, className }) {
   const [state, setState] = useState("idle");
   const [result, setResult] = useState(null);
 
@@ -43,10 +46,15 @@ export function AiSuggestPanel({ hook, inquiry, onAdopt, className }) {
     hook.clearAdopted();
   }, [inquiry, hook]);
 
+  // context 는 ref 로 최신값만 읽는다 — deps 에 넣으면 인라인 객체가
+  // 리렌더마다 새 참조가 되어 요청 콜백이 계속 재생성된다.
+  const contextRef = useRef(context);
+  contextRef.current = context;
+
   const request = useCallback(async () => {
     if (!inquiry || state === "loading") return;
     setState("loading");
-    setResult(await hook.requestAnswer(inquiry));
+    setResult(await hook.requestAnswer(inquiry, contextRef.current));
     setState("done");
   }, [hook, inquiry, state]);
 

package/vue.d.ts

@@ -7,6 +7,8 @@ export type { AiSuggestView } from "./view.js";
 export interface AiSuggestPanelProps {
   hook: CxHook;
   inquiry?: string;
+  /** 고객 상황 — 기기·버전·융합 키 */
+  context?: Record<string, string> | null;
   /** 바깥 배치용 (레이아웃만 — 색·간격은 styles.css 변수로) */
   className?: string;
 }

package/vue.js

@@ -30,6 +30,8 @@ export const AiSuggestPanel = defineComponent({
   props: {
     hook: { type: Object, required: true },
     inquiry: { type: String, default: "" },
+    /** 고객 상황 — 기기·버전·융합 키 (요청 시점 최신값 사용) */
+    context: { type: Object, default: null },
     /** 바깥 배치용 (레이아웃만 — 색·간격은 styles.css 변수로) */
     className: { type: String, default: "" },
   },
@@ -53,7 +55,9 @@ export const AiSuggestPanel = defineComponent({
     const request = async () => {
       if (!props.inquiry || state.value === "loading") return;
       state.value = "loading";
-      result.value = await props.hook.requestAnswer(props.inquiry);
+      result.value = await props.hook.requestAnswer(
+        props.inquiry, props.context || undefined,
+      );
       state.value = "done";
     };