@fcg-labs/cx-agent-hook 0.2.1 → 0.2.3

package/client.js

@@ -35,6 +35,8 @@ const PATHS = {
     answerStream: (d) => `/v1/domains/${d}/answer/stream`,
     feedback: (d) => `/v1/domains/${d}/feedback`,
     ingress: (d) => `/v1/domains/${d}/ingress`,
+    // 조사 접점 (E-8) — 트리거는 큐 적재만, 상태는 경량 메타만 (허브 계약)
+    investigation: (d) => `/v1/domains/${d}/investigations`,
   },
   // platform 은 인그레스 API 미제공 (공장 큐레이션 파이프라인이 담당)
 };
@@ -525,6 +527,67 @@ export class CxAgentClient {
     this.onError(err, { op: "logInquiry", code });
     return { ok: false, inquiryId: null, duplicate: false, error: code };
   }
+
+  /** 조사 요청 (E-8) — 허브 큐 적재만. 실행·판정은 공장 몫이라 즉시 돌아온다.
+   *  활성 요청 재제출은 허브가 멱등 처리한다 (중복 큐잉 없음). */
+  async requestInvestigation(externalId, { userId, subUserId } = {}) {
+    if (this.api !== "hub" || !externalId) {
+      return { ok: false, status: "", error: "unsupported" };
+    }
+    try {
+      const { status, data } = await this._post(
+        PATHS.hub.investigation(this.domain),
+        {
+          external_id: String(externalId),
+          user_id: userId != null ? String(userId) : "",
+          sub_user_id: subUserId != null ? String(subUserId) : "",
+        },
+      );
+      if (status === 200 || status === 201) {
+        return { ok: true, status: data.status || "queued", error: null };
+      }
+      this.onError(new Error(`HTTP ${status}`),
+        { op: "requestInvestigation", code: data.error || "http_error" });
+      return { ok: false, status: "", error: data.error || "http_error" };
+    } catch (err) {
+      this.onError(err, { op: "requestInvestigation", code: "network_error" });
+      return { ok: false, status: "", error: "network_error" };
+    }
+  }
+
+  /** 조사 상태 (E-8) — 경량 메타만 온다 {status, job_id}. 리포트 본문은
+   *  공장 밖 불반출 계약이라 이 표면에 존재하지 않는다. */
+  async investigationStatus(externalId) {
+    if (this.api !== "hub" || !externalId) {
+      return { ok: false, status: "", error: "unsupported" };
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const res = await this.fetchImpl(
+        this.baseUrl + PATHS.hub.investigation(this.domain)
+          + `/${encodeURIComponent(String(externalId))}/status`,
+        {
+          headers: { "Authorization": `Bearer ${this.token}` },
+          signal: controller.signal,
+        },
+      );
+      const data = await res.json().catch(() => ({}));
+      if (res.status === 200) {
+        return { ok: true, status: data.status || "",
+                 jobId: data.job_id || 0, error: null };
+      }
+      if (res.status === 404) {
+        return { ok: true, status: "none", jobId: 0, error: null };
+      }
+      return { ok: false, status: "", error: data.error || "http_error" };
+    } catch (err) {
+      this.onError(err, { op: "investigationStatus", code: "network_error" });
+      return { ok: false, status: "", error: "network_error" };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
 }
 
 export default CxAgentClient;

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

@@ -52,9 +52,15 @@ export function createCxHook(config = {}) {
     // 화면 언어. 소비처가 이미 아는 값이라 setup 에서 한 번 넘기면 끝이고,
     // 이후 문구는 전부 훅이 낸다 — 고객사가 사유별 문구를 알 필요가 없다.
     locale, messages: messageOverrides,
+    // 중앙 설정 부트스트랩 (허브 GET client-config) — 기본 꺼짐(후방호환).
+    // 켜면 locale·문구·기능 플래그를 허브 발행분으로 병합한다. **명시 인자가
+    // 항상 이긴다** — 로컬이 정한 값은 원격이 못 덮는다. 전송 3요소(baseUrl·
+    // token·domain)는 부트스트랩의 닭-달걀이라 중앙화 대상이 아니다.
+    bootstrap = false,
     ...rest
   } = config;
   const messages = resolveMessages(locale, messageOverrides);
+  let flags = {};
   const client =
     baseUrl && token && domain
       ? new CxAgentClient({
@@ -86,9 +92,63 @@ export function createCxHook(config = {}) {
     send(id);
   };
 
+  const applyRemoteConfig = (remote) => {
+    if (!remote || typeof remote !== "object") return;
+    if (remote.locale || remote.messages) {
+      // 원격 문구 위에 로컬 override 재적용 — 로컬 우선 규칙을 병합 순서로 강제
+      const next = resolveMessages(locale || remote.locale, {
+        ...(remote.messages || {}),
+        ...(messageOverrides || {}),
+      });
+      Object.assign(messages, next);
+    }
+    if (remote.flags && typeof remote.flags === "object") {
+      flags = { ...remote.flags };
+    }
+  };
+
+  const fetchRemoteConfig = async () => {
+    const doFetch = rest.fetchImpl || (typeof fetch !== "undefined" ? fetch : null);
+    if (!doFetch) return;
+    const cacheKey = `cx-agent-config:${domain}`;
+    try {
+      if (typeof sessionStorage !== "undefined") {
+        const cached = JSON.parse(sessionStorage.getItem(cacheKey) || "null");
+        if (cached && Date.now() - cached.at < 5 * 60 * 1000) {
+          applyRemoteConfig(cached.config);
+          return;
+        }
+      }
+    } catch { /* 캐시 실패는 무시 — 네트워크로 진행 */ }
+    const res = await doFetch(
+      `${String(baseUrl).replace(/\/$/, "")}/v1/domains/${domain}/client-config`,
+      { headers: { Authorization: `Bearer ${token}` } },
+    );
+    if (!res.ok) return; // 404(미발행) 포함 — 정적 설정으로 동작 (fail-soft)
+    const remote = await res.json();
+    applyRemoteConfig(remote);
+    try {
+      if (typeof sessionStorage !== "undefined") {
+        sessionStorage.setItem(
+          cacheKey, JSON.stringify({ at: Date.now(), config: remote }),
+        );
+      }
+    } catch { /* 저장 실패 무시 */ }
+  };
+
+  // 부트스트랩은 백그라운드 — 화면을 막지 않는다. 기다리고 싶은 소비처만
+  // ready 를 await 한다 (실패도 resolve — 훅은 항상 동작 가능 상태).
+  const ready = (bootstrap && client && api === "hub")
+    ? fetchRemoteConfig().catch(() => {})
+    : Promise.resolve();
+
   return {
     /** 세 값이 다 있으면 true */
     enabled: Boolean(client),
+    /** 부트스트랩 완료 신호 — bootstrap 미사용 시 즉시 resolve */
+    ready,
+    /** 중앙 발행 기능 플래그 — 부트스트랩 전/미발행이면 빈 객체 */
+    get flags() { return flags; },
     /** setup 에서 정해진 화면 언어 (정규화된 값) */
     locale: normalizeLocale(locale),
     /** 이 훅의 문구 한 벌 — 패널이 UI 라벨까지 여기서 가져간다 */
@@ -105,6 +165,19 @@ export function createCxHook(config = {}) {
       return client.getAnswer(inquiry, context);
     },
 
+    /** 조사 요청 (E-8) — "이 케이스 깊이 조사해줘" 트리거. 큐 적재만 하고 즉시
+     * 돌아온다 — 결과는 investigationStatus 로 폴링, 리포트 검수는 공장 웹. */
+    requestInvestigation(externalId, identity) {
+      if (!client) return Promise.resolve({ ok: false, status: "", error: "not_configured" });
+      return client.requestInvestigation(externalId, identity);
+    },
+
+    /** 조사 상태 (E-8) — {status: none|queued|running|succeeded|failed, jobId} */
+    investigationStatus(externalId) {
+      if (!client) return Promise.resolve({ ok: false, status: "", error: "not_configured" });
+      return client.investigationStatus(externalId);
+    },
+
     /** 초안 직주입 스트리밍 — 답변 에디터에 AI 초안을 직접 흘려 쓴다.
      *
      * 패널·채택 버튼 없는 흐름의 정본이다: 소비처는 에디터 접근자(getDraft·
@@ -137,13 +210,24 @@ export function createCxHook(config = {}) {
         return { promise: Promise.resolve({ ...NOT_CONFIGURED, declinedReason: "" }),
                  abort: () => {} };
       }
-      // 새 스트림 = 이전 채택 무효 (문의가 같아도 초안이 바뀐다)
-      adoptedAnswerId = null;
+      // 새 스트림 = 이전 채택의 **교체 시도** (0.2.3). 확정(성공) 전까지
+      // 폐기하지 않고 보류한다 — 즉시 null 로 지우던 침묵 소거는 ① 실패 시
+      // 원복이 텍스트만 되고 채택 id 는 유실돼 verbatim 발송이 원장에서
+      // 빠졌고 ② 상담사가 명백히 버린 이전 제안이 기각 신호 없이 영구
+      // 미확인으로 남았다 (2026-08-10 적대 검증).
+      const supersededId = adoptedAnswerId;
+      adoptedAnswerId = null; // 스트림 중 발송이 낡은 id 로 귀속되는 것 방지
 
-      // 호칭 개인화 — 이름은 융합 키(IDENTITY)라 LLM 에 반출되지 않는다.
-      // 서버는 "안녕하세요 고객님"까지만 쓰고, 이름은 초안이 돌아온 뒤
-      // 인사말 한 곳에만 끼운다 (본문 중 다른 "고객님"은 건드리지 않음).
+      // 호칭 개인화 — 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(
@@ -153,6 +237,7 @@ export function createCxHook(config = {}) {
           : text;
 
       const controller = new AbortController();
+      let aborted = false;
       let accumulated = "";
       let pending = null;
       const flushDraft = () => { pending = null; setDraft(personalize(accumulated)); };
@@ -166,7 +251,7 @@ export function createCxHook(config = {}) {
 
       status(messages.ui_requesting);
       setDraft("");
-      const promise = client.getAnswerStream(inquiry, context, {
+      const promise = client.getAnswerStream(inquiry, contextWithName, {
         signal: controller.signal,
         onDelta(text) { accumulated += text; queueDraft(); },
         onRestart() {
@@ -181,20 +266,42 @@ export function createCxHook(config = {}) {
         },
       }).then((result) => {
         clearPending();
+        if (aborted) {
+          // 소비자 주도 중단 (문의 전환 등) — 화면은 소비자가 이미 재구성했다.
+          // 여기서 원복하면 **이전 문의의 초안이 새 문의 에디터에 주입**된다
+          // (0.2.3 — A 답변이 B 로 발송될 수 있던 오염 경로). 아무것도 안 만진다.
+          return result;
+        }
         if (result.answered) {
           setDraft(personalize(result.answer)); // 정본 확정 (strip+호칭 반영)
-          adoptedAnswerId = result.answerId ?? null;
+          const newId = result.answerId ?? null;
+          if (supersededId && supersededId !== newId) {
+            // 교체 확정 — 이전 제안은 기각으로 원장에 남긴다 (침묵 소거 금지).
+            // fire-and-forget: 실패해도 발송 UX 무간섭.
+            client.discarded(supersededId, "", "redraft");
+          }
+          adoptedAnswerId = newId;
           status("");
         } else {
-          // 실패·거절 — 미완성 텍스트를 에디터에 남기지 않고 원래 초안 복원
+          // 실패·거절 — 미완성 텍스트를 에디터에 남기지 않고 원래 초안 복원.
+          // 채택 기록도 함께 원복 — 텍스트만 되돌리면 복원된 이전 초안의
+          // verbatim 발송이 원장에서 빠진다 (0.2.3 비대칭 수정).
           setDraft(existing);
+          adoptedAnswerId = supersededId;
           status(textOf(messages, result.declinedReason || "unknown"));
         }
         return result;
       });
       return {
         promise,
-        abort: () => { clearPending(); controller.abort(); },
+        abort: () => {
+          // 중단 = 화면 상태는 소비자 소유, 원장 상태는 요청 전으로 복귀 —
+          // 직후 소비자의 폐기 훅(discarded)이 이전 채택 id 로 발화할 수 있다.
+          aborted = true;
+          adoptedAnswerId = supersededId;
+          clearPending();
+          controller.abort();
+        },
       };
     },
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fcg-labs/cx-agent-hook",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "FCG CX Agent 후킹 SDK — 서빙 답변 수신 + CS팀 교정(점수·수정·발송) 후킹. 의존성 0, CMS에 install만으로 이식",
   "type": "module",
   "main": "index.js",
@@ -100,4 +100,4 @@
     "access": "public"
   },
   "//name": "스코프는 @fcg-labs — org 소유이고 @fcg-labs/tlm 과 같은 자리다. @fcg 는 우리 것이 아니다(발행 불가)."
-}
+}