@fcg-labs/cx-agent-hook 0.2.2 → 0.3.0

package/element.js

@@ -24,21 +24,30 @@
  * 클래스를 모듈 최상위에서 만들지 않는 이유: `HTMLElement` 가 없는 곳(SSR·Node)
  * 에서 import 만 해도 죽는다. 등록 시점에 만든다.
  */
-import { aiSuggestView, CLS } from "./view.js";
+import { aiSuggestTree, aiSuggestView, CLS } from "./view.js";
 
 export { aiSuggestView };
 
 /** 기본 태그 이름 */
 export const TAG = "cx-ai-suggest";
 
-function el(tag, className, ...children) {
-  const node = document.createElement(tag);
-  if (className) node.className = className;
-  for (const c of children) {
-    if (c === null || c === false || c === undefined) continue;
-    node.append(c);
+/** 트리 노드 → DOM — 구조는 view.aiSuggestTree 가 소유한다. */
+function renderNode(node, actions) {
+  const dom = document.createElement(node.tag);
+  if (node.cls) dom.className = node.cls;
+  if (node.tag === "button") {
+    dom.type = node.type || "button";
+    dom.disabled = Boolean(node.disabled);
   }
-  return node;
+  if (node.action && actions[node.action]) {
+    dom.addEventListener("click", actions[node.action]);
+  }
+  if (node.children) {
+    for (const c of node.children) dom.append(renderNode(c, actions));
+  } else if (node.text !== undefined) {
+    dom.textContent = node.text;
+  }
+  return dom;
 }
 
 function createClass() {
@@ -100,49 +109,22 @@ function createClass() {
     #render() {
       this.replaceChildren();
       if (!this.#hook || !this.#hook.enabled) return;
-      const v = aiSuggestView({
+      const tree = aiSuggestTree({
         state: this.#state,
         result: this.#result,
         declineText: this.#hook.declineText,
         messages: this.#hook.messages,
       });
-
-      const button = el("button", CLS.button);
-      button.type = "button";
-      button.disabled = v.buttonDisabled;
-      button.textContent = v.buttonLabel;
-      button.addEventListener("click", () => this.#request());
-
-      const head = el("div", CLS.head, button);
-      if (v.showAdopt) {
-        const adopt = el("button", CLS.adopt);
-        adopt.type = "button";
-        adopt.textContent = v.adoptLabel;
-        adopt.addEventListener("click", () => this.#adopt());
-        head.append(adopt);
-      }
-
-      const root = el("div", CLS.root, head);
+      const actions = {
+        request: () => this.#request(),
+        adopt: () => this.#adopt(),
+      };
+      const root = document.createElement("div");
+      root.className = CLS.root;
       // 이 패널은 보통 "클릭하면 선택되는" 문의 행 안에 놓인다. 버튼을 누르려다
       // 행 선택이 토글되면 제안이 초기화된다.
       root.addEventListener("click", (e) => e.stopPropagation());
-
-      if (v.body.kind === "answer") {
-        const body = el("div", CLS.body);
-        const answer = el("div", CLS.answer);
-        answer.textContent = v.body.text;
-        body.append(answer);
-        if (v.body.evidence.length > 0) {
-          const ev = el("div", CLS.evidence);
-          ev.textContent = `${v.body.evidenceLabel}: ${v.body.evidence.join(" · ")}`;
-          body.append(ev);
-        }
-        root.append(body);
-      } else if (v.body.kind === "declined") {
-        const declined = el("div", CLS.declined);
-        declined.textContent = v.body.text;
-        root.append(declined);
-      }
+      for (const node of tree.children) root.append(renderNode(node, actions));
       this.append(root);
     }
   };

package/index.d.ts

@@ -13,6 +13,8 @@ export type { AnswerResult, ApiTarget };
 export type CxHookConfig = Partial<CxAgentConfig> & {
   /** 화면 언어. 한 번 넘기면 이후 문구는 전부 훅이 낸다. 미지정이면 "en". */
   locale?: string;
+  /** 중앙 설정 부트스트랩 (허브 client-config) — 기본 false. 명시 인자가 항상 이긴다. */
+  bootstrap?: boolean;
   /** 특정 문구만 덮어쓰기 — 나머지는 로케일 값 그대로 */
   messages?: Record<string, string>;
 };
@@ -30,6 +32,19 @@ export declare function declineText(reason: string, locale?: string): string;
 export interface CxHook {
   /** 주소·토큰·도메인이 다 있으면 true */
   enabled: boolean;
+  /** 부트스트랩 완료 신호 — bootstrap 미사용 시 즉시 resolve (실패도 resolve) */
+  ready: Promise<void>;
+  /** 중앙 발행 기능 플래그 — 부트스트랩 전/미발행이면 빈 객체 */
+  readonly flags: Record<string, unknown>;
+  /** 조사 요청 (E-8) — 허브 큐 적재만, 실행·검수는 공장. 활성 중복은 멱등 */
+  requestInvestigation(
+    externalId: string | number,
+    identity?: { userId?: string | number; subUserId?: string | number },
+  ): Promise<{ ok: boolean; status: string; error: string | null }>;
+  /** 조사 상태 (E-8) — 경량 메타만: none|queued|running|succeeded|failed */
+  investigationStatus(
+    externalId: string | number,
+  ): Promise<{ ok: boolean; status: string; jobId?: number; error: string | null }>;
   /** setup 에서 정해진 화면 언어 (정규화된 값) */
   locale: Locale;
   /** 이 훅의 문구 한 벌 — UI 라벨 포함 */

package/index.js

@@ -1,21 +1,26 @@
 /**
- * @fcg-labs/cx-agent-hook — FCG CX Agent 후킹 SDK (공개 표면).
+ * @fcg-labs/cx-agent-hook — FCG CX Agent 후킹 SDK (0.2.x 호환 공개 표면).
  *
- * 소비처(고객사 관리자 화면)가 닿는 것은 이 파일과 `./react` 뿐이다.
+ * 소비처(고객사 관리자 화면)가 닿는 것은 이 파일과 어댑터 서브패스뿐이다.
  * 전송 계층(`CxAgentClient`)은 `client.js` 에 있고 **밖으로 내보내지 않는다** —
  * 열어 두면 새 능력을 붙일 때 자연히 그리로 내려가고, 그 순간 `answer_id`
  * 수명 관리 같은 제품 지식이 다시 고객사 코드로 흩어진다. 능력이 모자라면
- * 저수준을 노출하는 게 아니라 **여기 표면을 채운다.**
+ * 저수준을 노출하는 게 아니라 **표면을 채운다.**
  *
- *   ① 답변 제안 수신          requestAnswer
+ *   ① 답변 제안 수신          requestAnswer · composeDraft
  *   ② 상담사 판단 후킹         answerSent · scored · edited · discarded
  *   ③ 문의·답변 쌍 적재        inquirySent   ★ 이게 빠지면 아무것도 안 쌓인다
  *
+ * 0.3.0: 구현은 `agent.js`(CxAgent) + `session.js`(InquirySession) 로
+ * 객체화됐다. 이 루트 표면은 그 위의 호환층(compat.js)이다 — 문의별 세션
+ * 상태·초안 영속이 필요하면 `@fcg-labs/cx-agent-hook/agent` 로 올라간다.
+ *
  * 원칙: 의존성 0 (내장 fetch), 어떤 메서드도 throw 하지 않는다.
  */
-import { CxAgentClient } from "./client.js";
 import { LOCALES, MESSAGES, normalizeLocale, resolveMessages } from "./locales.js";
+import { textOf } from "./agent.js";
 
+export { createCxHook } from "./compat.js";
 export { LOCALES, MESSAGES, normalizeLocale };
 
 /** 사유 코드 → 상담사가 읽을 평문.
@@ -26,225 +31,3 @@ export { LOCALES, MESSAGES, normalizeLocale };
 export function declineText(reason, locale) {
   return textOf(resolveMessages(locale), reason);
 }
-
-/** 문구 한 벌에서 사유 하나 꺼내기. 기계 코드를 화면에 노출하지 않는다. */
-function textOf(messages, reason) {
-  const known = messages[reason];
-  if (known) return known;
-  if (String(reason || "").startsWith("http_")) return messages.http_error;
-  return messages.unknown;
-}
-
-const NOT_CONFIGURED = {
-  ok: false, answered: false, answer: "", answerId: null,
-  evidence: [], declinedReason: "not_configured", raw: {},
-};
-
-/** 후킹 한 벌을 만든다 — 미설정이면 전부 무동작.
- *
- * 소비하는 쪽이 써야 할 것은 **주소·토큰·도메인 세 값을 자기 빌드 방식으로 읽어
- * 넘기는 일**뿐이다. 미설정 판정, 널 가드, 실패 시 돌려줄 모양, 사유 문구,
- * 채택 식별자의 수명은 전부 여기에 있다.
- */
-export function createCxHook(config = {}) {
-  const {
-    baseUrl, token, domain, api = "hub", onError,
-    // 화면 언어. 소비처가 이미 아는 값이라 setup 에서 한 번 넘기면 끝이고,
-    // 이후 문구는 전부 훅이 낸다 — 고객사가 사유별 문구를 알 필요가 없다.
-    locale, messages: messageOverrides,
-    ...rest
-  } = config;
-  const messages = resolveMessages(locale, messageOverrides);
-  const client =
-    baseUrl && token && domain
-      ? new CxAgentClient({
-          baseUrl, token, domain, api,
-          // 후킹 실패는 CS 업무와 무관 — 기록만 하고 화면을 막지 않는다.
-          onError:
-            onError ||
-            ((err, ctx) => console.warn("[cx-agent-hook]", ctx.op, err.message)),
-          ...rest,
-        })
-      : null;
-
-  // 상담사가 어느 제안을 에디터에 넣었는지. **이 기록이 gold 쌍의 유일한 근거다**
-  // — 발송된 최종 문구가 어느 answer_id 의 교정본인지 잇는 값이라, 여기가 비면
-  // 후킹은 일어나도 "AI 초안 → 사람 최종본" 델타가 성립하지 않는다.
-  // 고객사가 들고 다니게 하면 지우는 시점(문의 전환·발송 완료)까지 남의 코드에
-  // 흩어진다. 라이브러리가 소유한다.
-  let adoptedAnswerId = null;
-
-  /** 채택된 제안에 대한 교정 후킹. 채택이 없었으면 조용히 무동작.
-   *
-   * `consume` 이 true 면 보낸 뒤 기록을 비운다 — 발송·폐기는 그 제안에 대한
-   * 마지막 판단이라 두 번 세면 안 되고, 점수·수정은 발송 전에 여러 번 올 수 있다.
-   */
-  const emit = (send, consume) => {
-    const id = adoptedAnswerId;
-    if (consume) adoptedAnswerId = null;
-    if (!client || !id) return;
-    send(id);
-  };
-
-  return {
-    /** 세 값이 다 있으면 true */
-    enabled: Boolean(client),
-    /** setup 에서 정해진 화면 언어 (정규화된 값) */
-    locale: normalizeLocale(locale),
-    /** 이 훅의 문구 한 벌 — 패널이 UI 라벨까지 여기서 가져간다 */
-    messages,
-    /** 사유 코드 → 이 훅의 언어로 된 평문 */
-    declineText(reason) {
-      return textOf(messages, reason);
-    },
-
-    /** 답변 제안 요청 — throw 하지 않음.
-     * context: 문의에 붙는 고객 상황(기기·버전·융합 키) — 선택. */
-    requestAnswer(inquiry, context) {
-      if (!client || !inquiry) return Promise.resolve(NOT_CONFIGURED);
-      return client.getAnswer(inquiry, context);
-    },
-
-    /** 초안 직주입 스트리밍 — 답변 에디터에 AI 초안을 직접 흘려 쓴다.
-     *
-     * 패널·채택 버튼 없는 흐름의 정본이다: 소비처는 에디터 접근자(getDraft·
-     * setDraft)와 상태 표시(setStatus)만 배선하고, 나머지 제품 판단 —
-     * 덮어쓰기 확인, 교정 재시작 처리, 실패 시 원복, 문구, **자동 채택 귀속**
-     * (직주입 = 채택이므로 성공 시 noteAdopted 를 훅이 스스로 부른다) — 은
-     * 전부 여기 있다. answerSent 의 consume 의미론은 그대로다.
-     *
-     * @param {object} opts
-     * @param {string} opts.inquiry
-     * @param {Record<string,string>} [opts.context]
-     * @param {()=>string} [opts.getDraft] 현재 초안 (덮어쓰기 가드용)
-     * @param {(text:string)=>void} opts.setDraft 초안 전체 치환 (누적 스냅샷)
-     * @param {(text:string)=>void} [opts.setStatus] 한 줄 상태 ("" = 지움)
-     * @param {()=>boolean} [opts.confirmOverwrite] 초안이 비어있지 않을 때 확인
-     * @returns {{promise: Promise<object>, abort: ()=>void}}
-     */
-    composeDraft({ inquiry, context, getDraft, setDraft, setStatus,
-                   confirmOverwrite, customerName } = {}) {
-      const status = (text) => { if (setStatus) setStatus(text || ""); };
-      const noop = { promise: Promise.resolve(NOT_CONFIGURED), abort: () => {} };
-      if (!client || !inquiry || typeof setDraft !== "function") {
-        status(textOf(messages, "not_configured"));
-        return noop;
-      }
-      const existing = typeof getDraft === "function"
-        ? String(getDraft() || "") : "";
-      if (existing.trim() && !(confirmOverwrite && confirmOverwrite())) {
-        // 상담사가 쓰던 초안이 우선한다 — 조용히 덮지 않는다.
-        return { promise: Promise.resolve({ ...NOT_CONFIGURED, declinedReason: "" }),
-                 abort: () => {} };
-      }
-      // 새 스트림 = 이전 채택 무효 (문의가 같아도 초안이 바뀐다)
-      adoptedAnswerId = null;
-
-      // 호칭 개인화 — 0.2.2: 이름을 context 로도 보낸다. 서버가 사설
-      // 서빙(AI_CS_LLM_PRIVATE)이면 인사말을 처음부터 이름으로 굽고,
-      // **저장은 하지 않는다**(로그에는 name_provided 마커만 — 서버 계약).
-      // 아래 클라 치환은 안전망으로 유지: 구 서버·클라우드 폴백처럼 이름
-      // 없이 "안녕하세요 고객님"으로 온 초안에만 작동하고, 서버가 이미
-      // 이름을 넣었으면 패턴이 안 맞아 no-op 이다.
-      const name = String(customerName || "").trim();
-      const contextWithName = name
-        ? { ...(context || {}), customerName: name }
-        : context;
-      const personalize = (text) =>
-        name
-          ? String(text).replace(
-              /안녕하세요[,]?\s*고객님/,
-              (m) => m.replace("고객님", `${name} 고객님`),
-            )
-          : text;
-
-      const controller = new AbortController();
-      let accumulated = "";
-      let pending = null;
-      const flushDraft = () => { pending = null; setDraft(personalize(accumulated)); };
-      const queueDraft = () => {
-        // trailing 스로틀 — 청크마다 리렌더하면 큰 화면이 버벅인다
-        if (pending === null) pending = setTimeout(flushDraft, 80);
-      };
-      const clearPending = () => {
-        if (pending !== null) { clearTimeout(pending); pending = null; }
-      };
-
-      status(messages.ui_requesting);
-      setDraft("");
-      const promise = client.getAnswerStream(inquiry, contextWithName, {
-        signal: controller.signal,
-        onDelta(text) { accumulated += text; queueDraft(); },
-        onRestart() {
-          // 계약 위반 교정 — 지금까지 보인 초안은 폐기본이다
-          clearPending();
-          accumulated = "";
-          setDraft("");
-          status(messages.ui_correcting);
-        },
-        onStage(phase) {
-          if (phase === "generating") status(messages.ui_requesting);
-        },
-      }).then((result) => {
-        clearPending();
-        if (result.answered) {
-          setDraft(personalize(result.answer)); // 정본 확정 (strip+호칭 반영)
-          adoptedAnswerId = result.answerId ?? null;
-          status("");
-        } else {
-          // 실패·거절 — 미완성 텍스트를 에디터에 남기지 않고 원래 초안 복원
-          setDraft(existing);
-          status(textOf(messages, result.declinedReason || "unknown"));
-        }
-        return result;
-      });
-      return {
-        promise,
-        abort: () => { clearPending(); controller.abort(); },
-      };
-    },
-
-    /** 제안을 에디터에 넣었다 (패널이 부른다) */
-    noteAdopted(answerId) {
-      adoptedAnswerId = answerId || null;
-    },
-    /** 채택 기록 폐기 — 다른 문의로 옮겼을 때 */
-    clearAdopted() {
-      adoptedAnswerId = null;
-    },
-    /** 지금 채택된 제안이 있나 (표시·검증용) */
-    get adoptedAnswerId() {
-      return adoptedAnswerId;
-    },
-
-    /** 답변 발송됨 — 채택본이었다면 gold 쌍으로 후킹 (fire-and-forget).
-     *
-     * 채택 없이 상담사가 직접 쓴 답변이면 아무 일도 안 한다. 한 번 보내면
-     * 기록을 비운다 — 같은 문의를 다시 발송해도 중복 교정이 쌓이지 않는다.
-     */
-    answerSent(finalText, agent) {
-      emit((id) => client.sent(id, finalText, agent), true);
-    },
-    /** 제안 품질 점수 1~5 (발송 전에 여러 번 올 수 있어 기록을 비우지 않는다) */
-    scored(score, agent) {
-      emit((id) => client.scored(id, score, agent), false);
-    },
-    /** 제안을 고쳐 썼다 — 초안↔최종본 델타 (발송 전 중간 저장 가능) */
-    edited(finalText, agent) {
-      emit((id) => client.edited(id, finalText, agent), false);
-    },
-    /** 제안을 버렸다 + 이유. 그 제안에 대한 마지막 판단이라 기록을 비운다. */
-    discarded(agent, note) {
-      emit((id) => client.discarded(id, agent, note), true);
-    },
-
-    /** 문의+상담사 최종답변 쌍 적재 (fire-and-forget, external_id 멱등).
-     *
-     * AI 제안을 안 써도 이것만 붙으면 광물이 쌓인다 — 인입의 유일한 통로.
-     */
-    inquirySent({ externalId, inquiry, reply, agent, meta } = {}) {
-      if (!client || !externalId || !inquiry) return;
-      client.logInquiry({ externalId, inquiry, reply, agent, meta });
-    },
-  };
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fcg-labs/cx-agent-hook",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "FCG CX Agent 후킹 SDK — 서빙 답변 수신 + CS팀 교정(점수·수정·발송) 후킹. 의존성 0, CMS에 install만으로 이식",
   "type": "module",
   "main": "index.js",
@@ -10,6 +10,10 @@
       "types": "./index.d.ts",
       "import": "./index.js"
     },
+    "./agent": {
+      "types": "./agent.d.ts",
+      "import": "./agent.js"
+    },
     "./react": {
       "types": "./react.d.ts",
       "import": "./react.js"
@@ -54,8 +58,13 @@
   "files": [
     "index.js",
     "index.d.ts",
+    "agent.js",
+    "agent.d.ts",
+    "session.js",
+    "compat.js",
     "client.js",
     "client.d.ts",
+    "MIGRATION.md",
     "view.js",
     "view.d.ts",
     "locales.js",

package/react.js

@@ -19,11 +19,25 @@
  */
 import { createElement as h, useCallback, useEffect, useRef, useState } from "react";
 
-import { aiSuggestView, CLS } from "./view.js";
+import { aiSuggestTree, aiSuggestView, CLS } from "./view.js";
 
 // 표시 판단은 프레임워크 중립 코어가 갖는다 — Vue·웹 컴포넌트와 같은 것을 쓴다.
 export { aiSuggestView };
 
+/** 트리 노드 → React 엘리먼트 — 구조는 view.aiSuggestTree 가 소유한다. */
+function renderNode(node, actions, key) {
+  const props = { key, className: node.cls };
+  if (node.tag === "button") {
+    props.type = node.type || "button";
+    props.disabled = Boolean(node.disabled);
+  }
+  if (node.action && actions[node.action]) props.onClick = actions[node.action];
+  const children = node.children
+    ? node.children.map((c, i) => renderNode(c, actions, i))
+    : node.text;
+  return h(node.tag, props, children);
+}
+
 /**
  * @param {object}   props
  * @param {object}   props.hook      createCxHook() 결과
@@ -66,7 +80,7 @@ export function AiSuggestPanel({ hook, inquiry, context, onAdopt, className }) {
 
   if (!hook || !hook.enabled) return null;
 
-  const view = aiSuggestView({
+  const tree = aiSuggestTree({
     state, result, declineText: hook.declineText, messages: hook.messages,
   });
 
@@ -78,40 +92,7 @@ export function AiSuggestPanel({ hook, inquiry, context, onAdopt, className }) {
       // 행 선택이 토글되면 제안이 초기화된다.
       onClick: (event) => event.stopPropagation(),
     },
-    h(
-      "div",
-      { className: CLS.head },
-      h(
-        "button",
-        {
-          type: "button",
-          className: CLS.button,
-          disabled: view.buttonDisabled,
-          onClick: request,
-        },
-        view.buttonLabel,
-      ),
-      view.showAdopt &&
-        h(
-          "button",
-          { type: "button", className: CLS.adopt, onClick: adopt },
-          view.adoptLabel,
-        ),
-    ),
-    view.body.kind === "answer" &&
-      h(
-        "div",
-        { className: CLS.body },
-        h("div", { className: CLS.answer }, view.body.text),
-        view.body.evidence.length > 0 &&
-          h(
-            "div",
-            { className: CLS.evidence },
-            `${view.body.evidenceLabel}: ${view.body.evidence.join(" · ")}`,
-          ),
-      ),
-    view.body.kind === "declined" &&
-      h("div", { className: CLS.declined }, view.body.text),
+    tree.children.map((node, i) => renderNode(node, { request, adopt }, i)),
   );
 }