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

package/client.js

@@ -37,6 +37,8 @@ const PATHS = {
     ingress: (d) => `/v1/domains/${d}/ingress`,
     // 조사 접점 (E-8) — 트리거는 큐 적재만, 상태는 경량 메타만 (허브 계약)
     investigation: (d) => `/v1/domains/${d}/investigations`,
+    // 처리 액션 (actions/1) — 실행 요청·상태·재조정. 정본: docs/contracts/action-contract-v1.md
+    actions: (d) => `/v1/domains/${d}/actions`,
   },
   // platform 은 인그레스 API 미제공 (공장 큐레이션 파이프라인이 담당)
 };
@@ -113,7 +115,7 @@ export class CxAgentClient {
    */
   constructor({ baseUrl, token, domain, api = "platform", retries = 2,
                 timeoutMs = 90000, onError, fetchImpl,
-                answer, ingress, feedback } = {}) {
+                answer, ingress, feedback, source = "cms" } = {}) {
     if (!baseUrl || !token || !domain) {
       throw new Error("@fcg-labs/cx-agent-hook: baseUrl·token·domain 은 필수입니다");
     }
@@ -140,6 +142,9 @@ export class CxAgentClient {
     }
     this.retries = retries;
     this.timeoutMs = timeoutMs;
+    // 인그레스 body.source — 문의가 어느 채널에서 왔는지의 테넌트 선언.
+    // "cms" 하드코딩이던 것을 0.3.0 에서 파라미터화 (기본값은 하위호환).
+    this.source = String(source || "cms");
     this.onError = onError || (() => {});
     this.fetchImpl = fetchImpl || globalThis.fetch.bind(globalThis);
   }
@@ -485,7 +490,7 @@ export class CxAgentClient {
       return this._inqFail(new Error("inquiry 필수"), "invalid_inquiry");
     }
     const body = {
-      source: "cms",
+      source: this.source,
       external_id: String(externalId),
       inquiry: String(inquiry),
       ...(reply ? { reply: String(reply) } : {}),
@@ -588,6 +593,123 @@ export class CxAgentClient {
       clearTimeout(timer);
     }
   }
+
+  // ── 처리 액션 (actions/1) ──────────────────────────────────────────────
+  //
+  // **재시도 0.** sendFeedback 의 5xx 재시도 루프를 여기 쓰면 비멱등 실행이 두 번
+  // 간다. 네트워크 오류면 호출자가 actionStatus(request_id) 로 원장을 묻고,
+  // 404(미도달 확정)일 때만 같은 request_id 로 1회 재전송한다 (client 밖 규칙).
+
+  /**
+   * 실행 요청. request_id 는 호출자(세션)가 발급·영속한 뒤 넘긴다 — 멱등 키.
+   * @returns {Promise<{ok:boolean, state:string, requestId:string, reasonCode:string,
+   *   message:string, actorAttested:string, auditRef:string, result:object|null,
+   *   deduplicated:boolean, error:string|null, httpStatus:number}>}
+   */
+  async requestAction({ requestId, offer, actorAssertion, actorClaimed, inquiryRef } = {}) {
+    if (this.api !== "hub" || !requestId || !offer || !offer.offer_id) {
+      return { ok: false, state: "", requestId: requestId || "", reasonCode: "",
+               message: "", actorAttested: "", auditRef: "", result: null,
+               deduplicated: false, error: "unsupported", httpStatus: 0 };
+    }
+    const body = {
+      request_id: String(requestId), offer_id: String(offer.offer_id),
+      event_id: String(offer.event_id || ""), action_key: String(offer.action_key || ""),
+      params_hash: String(offer.params_hash || ""), params: offer.params_bound || {},
+      actor_assertion: String(actorAssertion || ""), actor_claimed: String(actorClaimed || ""),
+      inquiry_ref: inquiryRef != null ? String(inquiryRef) : "",
+      confirmed_at: new Date().toISOString(),
+    };
+    try {
+      const { status, data } = await this._post(PATHS.hub.actions(this.domain), body);
+      const view = (d) => ({
+        state: d.state || "", requestId: d.request_id || String(requestId),
+        reasonCode: d.reason_code || "", message: d.message || "",
+        actorAttested: d.actor_attested || "", auditRef: d.audit_ref || "",
+        result: d.result ?? null, deduplicated: Boolean(d.deduplicated),
+      });
+      if (status === 200 || status === 202) {
+        return { ok: true, ...view(data), error: null, httpStatus: status };
+      }
+      // 409 offer_locked / request_conflict, 422 계약 위반, 503 잠김 — 그대로 전달
+      this.onError(new Error(`HTTP ${status}`), { op: "requestAction", code: data.error || "http_error" });
+      return { ok: false, ...view(data), error: data.error || `http_${status}`, httpStatus: status };
+    } catch (err) {
+      this.onError(err, { op: "requestAction", code: "network_error" });
+      return { ok: false, state: "", requestId: String(requestId), reasonCode: "", message: "",
+               actorAttested: "", auditRef: "", result: null, deduplicated: false,
+               error: "network_error", httpStatus: 0 };
+    }
+  }
+
+  /** 상태 조회 — 원장 뷰(result 없음). 404 = 허브에 기록 없음(미도달 확정). */
+  async actionStatus(requestId) {
+    if (this.api !== "hub" || !requestId) return { ok: false, state: "", error: "unsupported" };
+    return this._getJson(
+      PATHS.hub.actions(this.domain) + `/${encodeURIComponent(String(requestId))}`,
+      "actionStatus",
+      (status, data) => {
+        if (status === 200) return { ok: true, state: data.state || "", reasonCode: data.reason_code || "",
+                                     message: data.message || "", error: null };
+        if (status === 404) return { ok: true, state: "none", reasonCode: "", message: "", error: null };
+        return { ok: false, state: "", error: data.error || `http_${status}` };
+      },
+    );
+  }
+
+  /** 재조정 — lookup 전용 (재실행 아님). unknown 만 의미 있고 종단이면 그대로 온다. */
+  async actionReconcile(requestId) {
+    if (this.api !== "hub" || !requestId) return { ok: false, state: "", error: "unsupported" };
+    try {
+      const { status, data } = await this._post(
+        PATHS.hub.actions(this.domain) + `/${encodeURIComponent(String(requestId))}/reconcile`, {},
+      );
+      if (status === 200 || status === 202) {
+        return { ok: true, state: data.state || "", reasonCode: data.reason_code || "",
+                 message: data.message || "", actorAttested: data.actor_attested || "",
+                 auditRef: data.audit_ref || "", error: null };
+      }
+      return { ok: false, state: "", error: data.error || `http_${status}` };
+    } catch (err) {
+      this.onError(err, { op: "actionReconcile", code: "network_error" });
+      return { ok: false, state: "", error: "network_error" };
+    }
+  }
+
+  async _getJson(path, op, interpret) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const res = await this.fetchImpl(this.baseUrl + path, {
+        headers: { "Authorization": `Bearer ${this.token}` }, signal: controller.signal,
+      });
+      const data = await res.json().catch(() => ({}));
+      return interpret(res.status, data);
+    } catch (err) {
+      this.onError(err, { op, code: "network_error" });
+      return { ok: false, state: "", error: "network_error" };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}
+
+/** ULID (Crockford 26자) — request_id 발급. 의존성 0 (공장 event_ids 와 동형). */
+export function newRequestId(now = Date.now()) {
+  const A = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+  let ts = BigInt(now) & ((1n << 48n) - 1n);
+  const rnd = new Uint8Array(10);
+  if (typeof crypto !== "undefined" && crypto.getRandomValues) crypto.getRandomValues(rnd);
+  else for (let i = 0; i < 10; i++) rnd[i] = Math.floor(Math.random() * 256);
+  // 상위 48bit 시각 → 10자, 하위 80bit 무작위 → 16자 (공장 event_ids 와 동일 배치)
+  const out = [];
+  let t = ts;
+  for (let i = 0; i < 10; i++) { out.unshift(A[Number(t & 31n)]); t >>= 5n; }
+  let r = 0n;
+  for (const b of rnd) r = (r << 8n) | BigInt(b);
+  const tail = [];
+  for (let i = 0; i < 16; i++) { tail.unshift(A[Number(r & 31n)]); r >>= 5n; }
+  return out.join("") + tail.join("");
 }
 
 export default CxAgentClient;

package/compat.js

@@ -0,0 +1,67 @@
+/**
+ * createCxHook — 0.2.x 호환 표면 (내부용 모듈, exports 맵에 없다).
+ *
+ * 0.3.0 에서 구현이 CxAgent + InquirySession 으로 옮겨졌다. 이 파일은 그
+ * 위에 0.2.x 문서화 표면을 **비영속 기본 세션** 하나로 재구성한다 — 기존
+ * 소비처(와 시험 94건)는 글자 하나 안 바꾸고 그대로 동작한다.
+ *
+ * 0.2.x 와 0.3.0 의 관계:
+ *   - hook.noteAdopted/answerSent/... = 기본 세션의 동명 메서드
+ *   - hook.composeDraft = session.compose + 호출별 UI sink
+ *   - 문의별 상태·영속이 필요하면 `createCxAgent` + `agent.session()` 으로
+ *     올라간다 (MIGRATION.md)
+ */
+import { createCxAgent, notConfiguredResult, textOf } from "./agent.js";
+
+/** 후킹 한 벌을 만든다 — 미설정이면 전부 무동작. (0.2.x 표면 그대로) */
+export function createCxHook(config = {}) {
+  const agent = createCxAgent({
+    ...config,
+    // 0.2.x 훅은 문의별 세션 개념이 없다 — 영속은 세션 표면의 능력이다.
+    storage: { enabled: false, ...(config.storage || {}) },
+  });
+  // 훅 전체가 공유하는 단일 채택 슬롯 = 비영속 기본 세션 하나
+  const session = agent.session();
+
+  return {
+    enabled: agent.enabled,
+    ready: agent.ready,
+    get flags() { return agent.flags; },
+    locale: agent.locale,
+    messages: agent.messages,
+    declineText(reason) { return agent.declineText(reason); },
+
+    requestAnswer(inquiry, context) {
+      return agent.requestAnswer(inquiry, context);
+    },
+    requestInvestigation(externalId, identity) {
+      return agent.requestInvestigation(externalId, identity);
+    },
+    investigationStatus(externalId) {
+      return agent.investigationStatus(externalId);
+    },
+
+    /** 초안 직주입 스트리밍 — 세션 compose 에 호출별 UI sink 를 붙인다.
+     * 의미론(자동 채택·교체 기각·실패 원복·abort 무간섭)은 session.js 소유. */
+    composeDraft({ inquiry, context, getDraft, setDraft, setStatus,
+                   confirmOverwrite, customerName } = {}) {
+      if (!agent.enabled || !inquiry || typeof setDraft !== "function") {
+        if (setStatus) setStatus(textOf(agent.messages, "not_configured"));
+        return { promise: Promise.resolve(notConfiguredResult()), abort: () => {} };
+      }
+      session.attachUi({ getDraft, setDraft, setStatus });
+      return session.compose({ inquiry, context, customerName, confirmOverwrite });
+    },
+
+    noteAdopted(answerId) { session.noteAdopted(answerId); },
+    clearAdopted() { session.clearAdopted(); },
+    get adoptedAnswerId() { return session.adoptedAnswerId; },
+
+    answerSent(finalText, agentId) { session.answerSent(finalText, agentId); },
+    scored(score, agentId) { session.scored(score, agentId); },
+    edited(finalText, agentId) { session.edited(finalText, agentId); },
+    discarded(agentId, note) { session.discarded(agentId, note); },
+
+    inquirySent(payload) { agent.inquirySent(payload); },
+  };
+}

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);
     }
   };