@fcg-labs/cx-agent-hook 0.1.0

package/client.js

@@ -0,0 +1,359 @@
+/**
+ * 전송 계층 — HTTP 왕복, 재시도, 경로·토큰 규약. **패키지 내부용이다.**
+ *
+ * `exports` 맵에 없다. 소비처가 `@fcg-labs/cx-agent-hook` 로 닿을 수 있는 것은
+ * `createCxHook` 이고, 이 클래스는 그 안에서만 만들어진다.
+ *
+ * 왜 닫아 두나 (2026-08-03): 열어 두면 새 능력을 붙일 때 자연히 여기로 내려가고,
+ * 그 순간 `answer_id` 수명 관리 같은 제품 지식이 다시 고객사 코드로 흩어진다.
+ * 능력이 모자라면 여기를 노출하는 게 아니라 **훅 표면을 채우는 것**이 답이다.
+ *
+ * 원칙:
+ *   - 의존성 0 (내장 fetch) — 브라우저·Node 18+ 어디서나
+ *   - 후킹은 CS팀 업무를 절대 막지 않는다: sendFeedback 은 throw 하지 않고
+ *     재시도 후 { ok:false } 로 보고한다 (발송 UX 무간섭)
+ *   - 대상 전환 가능: platform(현 공장 API) ↔ hub(자산 허브 v1 경로)
+ */
+
+// 정본: src/agent_ax_config/store.py FEEDBACK_ACTIONS (언어 경계 사본 — 함께 바꿀 것)
+const FEEDBACK_ACTIONS = new Set(["scored", "edited", "sent", "discarded"]);
+
+const PATHS = {
+  platform: {
+    answer: (d) => `/api/domains/${d}/answer`,
+    feedback: (d) => `/api/domains/${d}/feedback`,
+  },
+  hub: {
+    // 허브가 답변을 중계한다 (POST → 내부 서빙 노드로 프록시 + 교정 미러링).
+    // 정본: hub/internal/api/server.go 의 answer 라우트.
+    //
+    // 이 값이 null 이던 시절의 주석은 "허브는 아직 답변 생성 미담당" 이었는데,
+    // 허브에 라우트가 생긴 뒤에도 SDK 가 그대로여서 hub 대상 getAnswer 가
+    // HTTP 를 타보지도 못하고 unsupported_api 로 단락됐다 (2026-07-31 감사).
+    answer: (d) => `/v1/domains/${d}/answer`,
+    feedback: (d) => `/v1/domains/${d}/feedback`,
+    ingress: (d) => `/v1/domains/${d}/ingress`,
+  },
+  // platform 은 인그레스 API 미제공 (공장 큐레이션 파이프라인이 담당)
+};
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export class CxAgentClient {
+  /**
+   * @param {object} config
+   * @param {string} config.baseUrl  예: "https://hub.fcg.example"
+   * @param {string} config.token    Bearer 토큰 (edge 등급)
+   * @param {string} config.domain   예: "acme_cs" (수집함 이름)
+   * @param {"platform"|"hub"} [config.api="platform"] 기본 대상
+   * @param {{baseUrl?:string, token?:string, api?:string}} [config.answer]
+   *   답변 생성 전용 대상. 공장(platform)과 허브가 서로 다른 주소·토큰을 쓰므로
+   *   하나만으로는 "답변 생성 + 문의 적재"를 동시에 못 한다 — 그 조합이 바로
+   *   CMS 가 필요로 하는 것이라, 능력별로 대상을 열어 둔다.
+   * @param {{baseUrl?:string, token?:string, api?:string}} [config.ingress]
+   *   문의 적재 전용 대상 (보통 허브).
+   * @param {{baseUrl?:string, token?:string, api?:string}} [config.feedback]
+   *   교정 후킹 전용 대상.
+   * @param {number} [config.retries=2]      피드백 재시도 횟수
+   * @param {number} [config.timeoutMs=90000] 답변 생성 시간제한.
+   *
+   *   실측(2026-07-31, 운영 허브 직접 호출 n=4): 16.7s · 25.9s · 30.5s · 59.7s.
+   *   LLM 호출이라 문의마다 크게 흔들린다. 기본값이 30s 이던 시절에는 절반이
+   *   시간초과로 죽었고, 화면에는 그냥 패널이 안 뜨는 것으로만 보였다 —
+   *   상담사도 개발자도 원인을 알 수 없는 침묵이다.
+   *
+   *   여유를 크게 두는 편이 맞다. 이 요청은 상담사를 막지 않으므로(그동안
+   *   수동 작성 가능) 오래 기다리는 비용은 작고, 일찍 끊는 비용은 크다.
+   *   n=4 는 분포를 말하기엔 적다 — 운영 로그가 쌓이면 다시 재라.
+   * @param {(err: Error, context: object) => void} [config.onError]
+   * @param {typeof fetch} [config.fetchImpl] 테스트 주입용
+   */
+  constructor({ baseUrl, token, domain, api = "platform", retries = 2,
+                timeoutMs = 90000, onError, fetchImpl,
+                answer, ingress, feedback } = {}) {
+    if (!baseUrl || !token || !domain) {
+      throw new Error("@fcg-labs/cx-agent-hook: baseUrl·token·domain 은 필수입니다");
+    }
+    if (!PATHS[api]) {
+      throw new Error(`@fcg-labs/cx-agent-hook: api 는 platform|hub (받음: ${api})`);
+    }
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.token = token;
+    this.domain = domain;
+    this.api = api;
+    // 능력별 대상 override — 미지정이면 기본 대상을 쓴다(하위호환).
+    this.targets = {};
+    for (const [cap, cfg] of Object.entries({ answer, ingress, feedback })) {
+      if (!cfg) continue;
+      const capApi = cfg.api || api;
+      if (!PATHS[capApi]) {
+        throw new Error(`@fcg-labs/cx-agent-hook: ${cap}.api 는 platform|hub (받음: ${capApi})`);
+      }
+      this.targets[cap] = {
+        baseUrl: (cfg.baseUrl || baseUrl).replace(/\/+$/, ""),
+        token: cfg.token || token,
+        api: capApi,
+      };
+    }
+    this.retries = retries;
+    this.timeoutMs = timeoutMs;
+    this.onError = onError || (() => {});
+    this.fetchImpl = fetchImpl || globalThis.fetch.bind(globalThis);
+  }
+
+  /**
+   * 능력(capability) → 실제 대상 해석.
+   * @returns {{baseUrl:string, token:string, path:((d:string)=>string)|null}}
+   */
+  _target(capability) {
+    const t = this.targets[capability] || {
+      baseUrl: this.baseUrl, token: this.token, api: this.api,
+    };
+    return {
+      baseUrl: t.baseUrl, token: t.token, api: t.api,
+      path: PATHS[t.api][capability] || null,
+    };
+  }
+
+  async _post(path, body, target) {
+    const { baseUrl, token } = target || { baseUrl: this.baseUrl, token: this.token };
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const res = await this.fetchImpl(baseUrl + path, {
+        method: "POST",
+        headers: {
+          "Authorization": `Bearer ${token}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+      const data = await res.json().catch(() => ({}));
+      return { status: res.status, data };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  /**
+   * 서빙 답변 요청. throw 하지 않는다 — ok 로 판별.
+   * @param {string} inquiry 고객 문의 원문
+   * @returns {Promise<{ok:boolean, answered:boolean, answer:string,
+   *   answerId:number|null, evidence:Array, declinedReason:string, raw:object}>}
+   */
+  async getAnswer(inquiry) {
+    const target = this._target("answer");
+    if (!target.path) {
+      // throw 하지 않는다 — 이 SDK 의 원칙은 "CS팀 업무를 절대 막지 않는다".
+      // 답변 대상이 안 잡혀 있으면 상담사는 수동 작성으로 계속 가면 된다.
+      this.onError(
+        new Error("답변 생성 대상이 설정되지 않았습니다 (answer.baseUrl 확인)"),
+        { op: "getAnswer" },
+      );
+      return {
+        ok: false, answered: false, answer: "", answerId: null,
+        evidence: [], declinedReason: "unsupported_api", raw: {},
+      };
+    }
+    try {
+      const { status, data } = await this._post(
+        target.path(this.domain), { inquiry }, target,
+      );
+      if (status !== 200) {
+        // 서버가 준 사유를 그대로 옮긴다. `http_503` 으로 뭉개면 "아직 안 켬"
+        // (answer_disabled) 과 "장애" (answer_unavailable) 가 같은 값이 되고,
+        // 화면은 켜지지도 않은 기능을 두고 "잠시 후 다시 시도" 라고 거짓말한다.
+        // 진실의 주인은 서버이고 SDK 는 전달만 한다.
+        //
+        // 필드명 `error` 는 허브·공장 양쪽이 같다:
+        //   허브   writeErr → {"error": code, "detail": ...}
+        //   공장   JSONResponse({"error": "serving_disabled"}, 503) 등
+        return {
+          ok: false, answered: false, answer: "", answerId: null,
+          evidence: [],
+          declinedReason: (data && data.error) || `http_${status}`,
+          raw: data,
+        };
+      }
+      return {
+        ok: true,
+        answered: Boolean(data.answered),
+        answer: data.answer || "",
+        answerId: data.answer_id ?? null,
+        evidence: data.evidence || [],
+        declinedReason: data.declined_reason || "",
+        raw: data,
+      };
+    } catch (err) {
+      this.onError(err, { op: "getAnswer" });
+      return {
+        ok: false, answered: false, answer: "", answerId: null,
+        evidence: [], declinedReason: "network_error", raw: {},
+      };
+    }
+  }
+
+  /**
+   * 교정 후킹 — CS팀 업무를 막지 않는다: throw 없이 재시도 후 결과 보고.
+   * @param {object} fb
+   * @param {number|string} fb.answerId
+   * @param {"scored"|"edited"|"sent"|"discarded"} fb.action
+   * @param {number} [fb.score]     scored 시 1~5 필수
+   * @param {string} [fb.finalText] 수정/발송된 최종 문구
+   * @param {string} [fb.agent]     CS 상담사 식별자
+   * @param {string} [fb.note]
+   * @returns {Promise<{ok:boolean, feedbackId:number|null, error:string}>}
+   */
+  async sendFeedback({ answerId, action, score, finalText, agent, note } = {}) {
+    // 계약 위반은 재시도해도 소용없다 — 즉시 보고
+    if (answerId === undefined || answerId === null || answerId === "") {
+      return this._fbFail(new Error("answerId 필수"), "invalid_answer_id");
+    }
+    if (!FEEDBACK_ACTIONS.has(action)) {
+      return this._fbFail(new Error(`action 무효: ${action}`), "invalid_action");
+    }
+    if (action === "scored" && !(Number.isInteger(score) && score >= 1 && score <= 5)) {
+      return this._fbFail(new Error("scored 는 1~5 정수 점수 필수"), "invalid_score");
+    }
+    const target = this._target("feedback");
+    if (!target.path) {
+      return this._fbFail(
+        new Error("교정 후킹 대상이 설정되지 않았습니다"), "unsupported_api",
+      );
+    }
+    const body = {
+      answer_id: target.api === "hub" ? String(answerId) : answerId,
+      action,
+      ...(score !== undefined ? { score } : {}),
+      ...(finalText ? { final_text: finalText } : {}),
+      ...(agent ? { agent } : {}),
+      ...(note ? { note } : {}),
+    };
+    const path = target.path(this.domain);
+    let lastErr = null;
+    for (let attempt = 0; attempt <= this.retries; attempt++) {
+      try {
+        const { status, data } = await this._post(path, body, target);
+        if (status === 200) {
+          return { ok: true, feedbackId: data.feedback_id ?? data.id ?? null, error: "" };
+        }
+        // 4xx 는 계약 문제 — 재시도 무의미
+        if (status >= 400 && status < 500) {
+          return this._fbFail(
+            new Error(`http_${status}: ${JSON.stringify(data)}`), `http_${status}`,
+          );
+        }
+        lastErr = new Error(`http_${status}`);
+      } catch (err) {
+        lastErr = err;
+      }
+      if (attempt < this.retries) {
+        await sleep(300 * (attempt + 1));
+      }
+    }
+    return this._fbFail(lastErr || new Error("unknown"), "network_error");
+  }
+
+  _fbFail(err, code) {
+    this.onError(err, { op: "sendFeedback", code });
+    return { ok: false, feedbackId: null, error: code };
+  }
+
+  /** 발송 후킹 — CS팀이 실제로 내보낸 최종 문구 (gold 학습 쌍의 원천) */
+  sent(answerId, finalText, agent) {
+    return this.sendFeedback({ answerId, action: "sent", finalText, agent });
+  }
+
+  /** 점수 후킹 (1~5) */
+  scored(answerId, score, agent) {
+    return this.sendFeedback({ answerId, action: "scored", score, agent });
+  }
+
+  /** 수정 후킹 — 발송 전 편집 상태 공유 */
+  edited(answerId, finalText, agent) {
+    return this.sendFeedback({ answerId, action: "edited", finalText, agent });
+  }
+
+  /** 폐기 후킹 — 품질 경보 신호 */
+  discarded(answerId, agent, note) {
+    return this.sendFeedback({ answerId, action: "discarded", agent, note });
+  }
+
+  /**
+   * 문의 적재 후킹 — 신규 문의(+상담사 최종 답변)를 허브로.
+   * (external_id 기준 멱등 — 같은 문의를 여러 번 보내도 안전)
+   *
+   * AI 서빙 없이도 광물이 흐르는 통로: 문의+최종답변 쌍은 그대로
+   * 교재(학습) 후보가 된다. CS팀 업무를 막지 않는다 — throw 없음.
+   *
+   * @param {object} q
+   * @param {number|string} q.externalId 원 시스템 문의 id (멱등 키)
+   * @param {string} q.inquiry   고객 문의 원문 (필수)
+   * @param {string} [q.reply]   상담사 최종 답변 (있으면 Q/A 학습 후보)
+   * @param {string} [q.agent]   CS 상담사 식별자
+   * @param {object} [q.meta]    부가 정보 (문자열 값만)
+   * @returns {Promise<{ok:boolean, inquiryId:number|null, duplicate:boolean, error:string}>}
+   */
+  async logInquiry({ externalId, inquiry, reply, agent, meta } = {}) {
+    const target = this._target("ingress");
+    if (!target.path) {
+      return this._inqFail(
+        new Error("문의 적재 대상이 설정되지 않았습니다 (ingress.baseUrl 확인)"),
+        "unsupported_api",
+      );
+    }
+    if (externalId === undefined || externalId === null || externalId === "") {
+      return this._inqFail(new Error("externalId 필수"), "invalid_external_id");
+    }
+    if (!inquiry || !String(inquiry).trim()) {
+      return this._inqFail(new Error("inquiry 필수"), "invalid_inquiry");
+    }
+    const body = {
+      source: "cms",
+      external_id: String(externalId),
+      inquiry: String(inquiry),
+      ...(reply ? { reply: String(reply) } : {}),
+      ...(agent || meta
+        ? { meta: { ...(meta || {}), ...(agent ? { agent: String(agent) } : {}) } }
+        : {}),
+    };
+    let lastErr = null;
+    for (let attempt = 0; attempt <= this.retries; attempt++) {
+      try {
+        const { status, data } = await this._post(
+          target.path(this.domain), body, target,
+        );
+        if (status === 200) {
+          return {
+            ok: true,
+            inquiryId: data.id ?? null,
+            duplicate: Boolean(data.duplicate),
+            error: "",
+          };
+        }
+        if (status >= 400 && status < 500) {
+          return this._inqFail(
+            new Error(`http_${status}: ${JSON.stringify(data)}`), `http_${status}`,
+          );
+        }
+        lastErr = new Error(`http_${status}`);
+      } catch (err) {
+        lastErr = err;
+      }
+      if (attempt < this.retries) {
+        await sleep(300 * (attempt + 1));
+      }
+    }
+    return this._inqFail(lastErr || new Error("unknown"), "network_error");
+  }
+
+  _inqFail(err, code) {
+    this.onError(err, { op: "logInquiry", code });
+    return { ok: false, inquiryId: null, duplicate: false, error: code };
+  }
+}
+
+export default CxAgentClient;

package/element.d.ts

@@ -0,0 +1,22 @@
+import type { CxHook } from "./index.js";
+
+export { aiSuggestView } from "./view.js";
+export type { AiSuggestView } from "./view.js";
+
+/** 기본 태그 이름 */
+export declare const TAG: "cx-ai-suggest";
+
+export interface CxAiSuggestElement extends HTMLElement {
+  hook: CxHook | null;
+  inquiry: string;
+}
+
+/** 커스텀 엘리먼트 등록. 두 번 불러도 안전하고, 브라우저가 아니면 무동작(false). */
+export declare function defineCxAiSuggest(tagName?: string): boolean;
+
+declare global {
+  interface HTMLElementTagNameMap { "cx-ai-suggest": CxAiSuggestElement }
+  interface HTMLElementEventMap {
+    "cx-adopt": CustomEvent<{ text: string; answerId: number | string | null }>;
+  }
+}

package/element.js

@@ -0,0 +1,148 @@
+/**
+ * AI 답변 제안 패널 — 표준 커스텀 엘리먼트 `<cx-ai-suggest>`.
+ *
+ * React·Vue 가 아닌 곳(Astro, Angular, 순수 HTML)이 쓰는 형태다. 프레임워크마다
+ * 어댑터를 하나씩 더 짜는 대신, **브라우저 표준 하나**로 나머지를 덮는다.
+ *
+ * ```html
+ * <cx-ai-suggest></cx-ai-suggest>
+ * <script type="module">
+ *   import { defineCxAiSuggest } from "@fcg-labs/cx-agent-hook/element";
+ *   import { createCxHook } from "@fcg-labs/cx-agent-hook";
+ *   defineCxAiSuggest();
+ *   const el = document.querySelector("cx-ai-suggest");
+ *   el.hook = createCxHook({ ... });
+ *   el.inquiry = "체중계가 안 켜져요";
+ *   el.addEventListener("cx-adopt", (e) => editor.value = e.detail.text);
+ * </script>
+ * ```
+ *
+ * **섀도 DOM 을 쓰지 않는다.** 쓰면 `styles.css` 가 안쪽에 닿지 않아 소비처가
+ * 스타일을 다시 넣어야 하고, 테마 변수(`--fcx-*`)도 끊긴다. 캡슐화보다 "한 벌의
+ * 스타일이 세 어댑터에 똑같이 적용되는 것"이 이 패널에는 중요하다.
+ *
+ * 클래스를 모듈 최상위에서 만들지 않는 이유: `HTMLElement` 가 없는 곳(SSR·Node)
+ * 에서 import 만 해도 죽는다. 등록 시점에 만든다.
+ */
+import { 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);
+  }
+  return node;
+}
+
+function createClass() {
+  return class CxAiSuggestElement extends HTMLElement {
+    #hook = null;
+    #inquiry = "";
+    #state = "idle";
+    #result = null;
+
+    /** createCxHook() 결과 */
+    get hook() { return this.#hook; }
+    set hook(value) { this.#hook = value; this.#render(); }
+
+    /** 대상 문의 원문 */
+    get inquiry() { return this.#inquiry; }
+    set inquiry(value) {
+      const next = value == null ? "" : String(value);
+      if (next === this.#inquiry) return;
+      this.#inquiry = next;
+      // 다른 문의로 옮기면 앞 문의의 제안이 남아 있으면 안 된다. 채택 기록도
+      // 같이 지운다 — 안 지우면 다음 문의를 발송할 때 엉뚱한 answer_id 로
+      // 후킹된다.
+      this.#state = "idle";
+      this.#result = null;
+      if (this.#hook) this.#hook.clearAdopted();
+      this.#render();
+    }
+
+    connectedCallback() { this.#render(); }
+
+    async #request() {
+      if (!this.#inquiry || this.#state === "loading") return;
+      this.#state = "loading";
+      this.#render();
+      this.#result = await this.#hook.requestAnswer(this.#inquiry);
+      this.#state = "done";
+      this.#render();
+    }
+
+    #adopt() {
+      const r = this.#result;
+      if (!r || !r.answered) return;
+      this.#hook.noteAdopted(r.answerId);
+      this.dispatchEvent(new CustomEvent("cx-adopt", {
+        detail: { text: r.answer, answerId: r.answerId },
+        bubbles: true,
+      }));
+    }
+
+    #render() {
+      this.replaceChildren();
+      if (!this.#hook || !this.#hook.enabled) return;
+      const v = aiSuggestView({
+        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);
+      // 이 패널은 보통 "클릭하면 선택되는" 문의 행 안에 놓인다. 버튼을 누르려다
+      // 행 선택이 토글되면 제안이 초기화된다.
+      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);
+      }
+      this.append(root);
+    }
+  };
+}
+
+/** 커스텀 엘리먼트 등록. 두 번 불러도 안전하고, 브라우저가 아니면 무동작. */
+export function defineCxAiSuggest(tagName = TAG) {
+  if (typeof window === "undefined" || !window.customElements) return false;
+  if (window.customElements.get(tagName)) return false;
+  window.customElements.define(tagName, createClass());
+  return true;
+}

package/index.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @fcg-labs/cx-agent-hook 공개 표면.
+ *
+ * 전송 계층(`CxAgentClient`)의 타입은 `client.d.ts` 에 있고 여기서 다시
+ * 내보내지 않는다 — 소비처가 그 타입을 손에 쥘 이유가 없어야 한다.
+ * 필요한 조각(설정·결과 모양)만 골라 노출한다.
+ */
+import type { AnswerResult, ApiTarget, CxAgentConfig } from "./client.js";
+
+export type { AnswerResult, ApiTarget };
+
+/** createCxHook 설정 — 주소·토큰·도메인 셋, 나머지는 선택 */
+export type CxHookConfig = Partial<CxAgentConfig> & {
+  /** 화면 언어. 한 번 넘기면 이후 문구는 전부 훅이 낸다. 미지정이면 "en". */
+  locale?: string;
+  /** 특정 문구만 덮어쓰기 — 나머지는 로케일 값 그대로 */
+  messages?: Record<string, string>;
+};
+
+/** 지원 로케일 (BCP 47 접두와 맞춘 값) */
+export type Locale = "ko" | "en" | "ja" | "zh-TW";
+export declare const LOCALES: Locale[];
+/** 로케일별 문구 한 벌 (제품 지식 — 소비처에 복제 금지) */
+export declare const MESSAGES: Record<Locale, Record<string, string>>;
+/** "ko-KR" 같은 표기를 지원 로케일로 정규화. 모르면 기본값("en"). */
+export declare function normalizeLocale(locale: unknown): Locale;
+/** 훅 없이 문구만 필요할 때 (테스트·미리보기). 보통은 hook.declineText 를 쓴다. */
+export declare function declineText(reason: string, locale?: string): string;
+
+export interface CxHook {
+  /** 주소·토큰·도메인이 다 있으면 true */
+  enabled: boolean;
+  /** setup 에서 정해진 화면 언어 (정규화된 값) */
+  locale: Locale;
+  /** 이 훅의 문구 한 벌 — UI 라벨 포함 */
+  messages: Record<string, string>;
+  /** 사유 코드 → 이 훅의 언어로 된 평문 */
+  declineText(reason: string): string;
+
+  requestAnswer(inquiry: string): Promise<AnswerResult>;
+
+  /** 제안을 에디터에 넣었다 (패널이 부른다) */
+  noteAdopted(answerId: number | string | null): void;
+  /** 채택 기록 폐기 — 문의 전환 시 */
+  clearAdopted(): void;
+  readonly adoptedAnswerId: number | string | null;
+
+  /** 발송됨 — 채택본이었을 때만 gold 쌍 후킹. 보낸 뒤 채택 기록을 비운다. */
+  answerSent(finalText: string, agent?: string): void;
+  /** 제안 품질 1~5 (발송 전 여러 번 가능 — 기록을 비우지 않는다) */
+  scored(score: number, agent?: string): void;
+  /** 제안을 고쳐 씀 — 초안↔최종본 델타 (기록을 비우지 않는다) */
+  edited(finalText: string, agent?: string): void;
+  /** 제안을 버림 + 이유. 마지막 판단이라 기록을 비운다. */
+  discarded(agent?: string, note?: string): void;
+
+  /** 문의+최종답변 쌍 적재 — 인입의 유일한 통로 (external_id 멱등) */
+  inquirySent(q: {
+    externalId: number | string;
+    inquiry: string;
+    reply?: string;
+    agent?: string;
+    meta?: Record<string, string>;
+  }): void;
+}
+
+/** 후킹 한 벌 생성 — 미설정(세 값 중 하나라도 빔)이면 전부 무동작 */
+export declare function createCxHook(config?: CxHookConfig): CxHook;