@solhun/feedback-kit-core 0.1.0

package/src/adapters/body.ts

@@ -0,0 +1,280 @@
+// 어댑터 공용 본문 렌더러.
+//
+// 왜 어댑터마다 따로 안 쓰고 여기 한 곳에 모으는가:
+// 제보를 어느 대상(라쏘런·Linear·Notion)으로 보내든 **사람이 읽는 내용은 같아야 한다.**
+// 어댑터마다 본문을 따로 조립하면 "Linear 로 보낸 제보에는 소스 경로가 없다" 같은
+// 차이가 조용히 생긴다. 그래서 어댑터는 이 함수가 만든 문자열을 자기 필드명에 실어
+// 나르기만 하고, 내용 구성에는 관여하지 않는다(DP-255 TC3·TC4).
+//
+// 접는 규칙도 여기 하나뿐이다:
+// - 대상이 받아주지 못하는 구조화 필드(진단·기기·요소 등)는 **본문 하단의 접힌 블록**에 넣는다.
+// - 접힌 블록은 제보 하나당 **정확히 하나**다. 어댑터가 추가로 접지 않는다.
+// - 사용자가 쓴 코멘트는 접지 않는다 — 읽는 사람이 제일 먼저 봐야 하는 내용이다.
+
+import type {
+  AppInfo,
+  ContextUser,
+  DeviceInfo,
+  DisplayInfo,
+  ElementInfo,
+  FeedbackKind,
+  FeedbackPriority,
+  FeedbackReport,
+  SourceMapping,
+  WebContext,
+} from "../types.js";
+import { sourceFromElement } from "../source-attr.js";
+
+/** 접힌 블록의 여는 태그. 테스트와 어댑터가 같은 문자열을 보게 상수로 둔다. */
+export const DETAILS_OPEN = "<details>";
+
+/** 접힌 블록의 요약줄. 대상에서 이 문구만 보이고 나머지는 접힌다. */
+export const DETAILS_SUMMARY = "<summary>진단 정보</summary>";
+
+/** 접힌 블록의 닫는 태그. */
+export const DETAILS_CLOSE = "</details>";
+
+/** 제목 최대 길이. 대상마다 제한이 다르지만, 한 줄로 읽히는 길이가 실질 상한이다. */
+export const TITLE_MAX_CHARS = 80;
+
+const KIND_LABEL: Record<FeedbackKind, string> = {
+  report: "제보",
+  annotation: "요소 주석",
+};
+
+const PRIORITY_LABEL: Record<FeedbackPriority, string> = {
+  unset: "미지정",
+  normal: "보통",
+  high: "높음",
+  urgent: "긴급",
+};
+
+/**
+ * 접힌 블록 **안에** 들어가는 자유 텍스트를 안전하게 만든다.
+ *
+ * `<` 만 막는 이유: 로그 메시지나 요소 텍스트에 `</details>` 가 들어 있으면 그 지점에서
+ * 블록이 닫혀 뒤쪽 진단이 통째로 펼쳐진다(제보 하나 = 접힌 블록 하나 규칙이 깨진다).
+ * `&` 까지 이스케이프하면 URL 쿼리(`?a=1&b=2`)가 읽기 어려워지는데, `&` 만으로는
+ * 블록이 깨지지 않으므로 그대로 둔다.
+ *
+ * 줄바꿈은 공백으로 접는다. 목록 한 줄이 여러 줄로 쪼개지면 표가 무너진다.
+ */
+function inline(value: string): string {
+  return value.replace(/</g, "&lt;").replace(/[\r\n\t]+/g, " ").trim();
+}
+
+/** `- 라벨: 값` 한 줄. 값이 비면 줄 자체를 만들지 않는다(빈 항목으로 지면을 채우지 않는다). */
+function kv(label: string, value: string | null | undefined): string | null {
+  if (value === null || value === undefined) return null;
+  const text = inline(value);
+  return text.length > 0 ? `- ${label}: ${text}` : null;
+}
+
+/** 객체를 한 줄 JSON 으로. 접힌 블록 안이라 이스케이프까지 거친다. */
+function json(value: unknown): string | null {
+  try {
+    const text = JSON.stringify(value);
+    return text === undefined || text === "{}" ? null : text;
+  } catch {
+    // 순환 참조 등. 제보 전체를 실패시킬 이유는 아니다.
+    return "(직렬화 불가)";
+  }
+}
+
+/** base64 길이에서 원본 바이트 수를 되돌린다(패딩 제외). */
+function approxBytesOfBase64(b64: string): number {
+  const padding = b64.endsWith("==") ? 2 : b64.endsWith("=") ? 1 : 0;
+  return Math.max(0, Math.floor((b64.length * 3) / 4) - padding);
+}
+
+function humanBytes(n: number): string {
+  return n < 1024 ? `${n} B` : `${(n / 1024).toFixed(1)} KB`;
+}
+
+/** `src/pages/Home.tsx:42` 형태. SourceMapping 에 칼럼이 없으므로 파일:줄까지다. */
+function formatSource(s: SourceMapping): string | null {
+  const file = s.sourceFile;
+  const line = typeof s.sourceLine === "number" ? s.sourceLine : null;
+  const filePart = file ? (line === null ? file : `${file}:${line}`) : null;
+  if (filePart && s.screenId) return `${filePart} (화면 ${s.screenId})`;
+  if (filePart) return filePart;
+  return s.screenId ? `화면 ${s.screenId}` : null;
+}
+
+function formatUser(u: ContextUser | null): string | null {
+  if (!u) return null;
+  const bits: string[] = [u.id ?? "(미상)"];
+  if (u.name) bits.push(u.name);
+  if (u.email) bits.push(u.email);
+  if (u.role) bits.push(`역할 ${u.role}`);
+  if (u.isGuest) bits.push("게스트");
+  return bits.join(" · ");
+}
+
+/** `button#save.primary` 형태의 셀렉터. 읽는 사람이 요소를 특정할 수 있으면 충분하다. */
+function elementSelector(el: ElementInfo): string {
+  if (el.selector) return el.selector;
+  let out = el.tag;
+  if (el.id) out += `#${el.id}`;
+  if (el.className) {
+    for (const cls of el.className.split(/\s+/)) {
+      if (cls) out += `.${cls}`;
+    }
+  }
+  return out;
+}
+
+function formatAppInfo(a: AppInfo): string | null {
+  const bits: string[] = [];
+  if (a.version) bits.push(a.version);
+  if (a.channel) bits.push(`채널 ${a.channel}`);
+  if (a.runtimeVersion) bits.push(`런타임 ${a.runtimeVersion}`);
+  if (a.updateId) bits.push(`업데이트 ${a.updateId}`);
+  return bits.length > 0 ? bits.join(" · ") : null;
+}
+
+function formatDevice(d: DeviceInfo): string | null {
+  const bits: string[] = [];
+  if (d.model) bits.push(d.model);
+  if (d.osName || d.osVersion) bits.push([d.osName, d.osVersion].filter(Boolean).join(" "));
+  if (d.deviceType) bits.push(d.deviceType);
+  return bits.length > 0 ? bits.join(" · ") : null;
+}
+
+function formatDisplay(d: DisplayInfo): string | null {
+  const bits: string[] = [];
+  if (d.width !== null && d.height !== null) bits.push(`${d.width}×${d.height}`);
+  if (d.pixelRatio !== null) bits.push(`@${d.pixelRatio}x`);
+  if (d.fontScale !== null) bits.push(`글꼴 배율 ${d.fontScale}`);
+  return bits.length > 0 ? bits.join(" · ") : null;
+}
+
+function formatViewport(v: WebContext["viewport"]): string | null {
+  const bits: string[] = [];
+  if (v.width !== null && v.height !== null) bits.push(`${v.width}×${v.height}`);
+  if (v.devicePixelRatio !== null) bits.push(`@${v.devicePixelRatio}x`);
+  return bits.length > 0 ? bits.join(" · ") : null;
+}
+
+/** 접힌 블록 안의 목록. 값이 없는 항목은 줄이 아예 없다. */
+function detailLines(report: FeedbackReport): string[] {
+  const c = report.context;
+  const out: (string | null)[] = [];
+
+  out.push(kv("종류", KIND_LABEL[report.kind]));
+  out.push(kv("우선순위", PRIORITY_LABEL[report.priority]));
+  out.push(kv("제출 ID", report.clientSubmissionId));
+  out.push(kv("작성 시각", report.createdAt));
+
+  out.push(kv("앱", c.app));
+  out.push(kv("플랫폼", c.platform));
+  out.push(kv("화면", c.screen));
+  out.push(kv("URL", c.url));
+  out.push(kv("소스", formatSource(c.source)));
+  out.push(kv("사용자", formatUser(c.user)));
+  out.push(kv("세션", c.sessionId));
+  out.push(
+    kv("수집 시각", c.timezone ? `${c.clientTimestamp} (${c.timezone})` : c.clientTimestamp)
+  );
+
+  if (report.element) {
+    const el = report.element;
+    out.push(kv("요소", elementSelector(el)));
+    out.push(kv("요소 CSS 경로", el.selector ?? null));
+    out.push(kv("요소 소스", formatSource(sourceFromElement(el))));
+    out.push(kv("요소 텍스트", el.text));
+    if (el.boundingBox) {
+      const b = el.boundingBox;
+      out.push(
+        kv(
+          "요소 위치",
+          `x ${Math.round(b.x)} · y ${Math.round(b.y)} · ${Math.round(b.width)}×${Math.round(
+            b.height
+          )}`
+        )
+      );
+    }
+    out.push(kv("요소 속성", json(el.attributes)));
+  }
+
+  if (report.pin) {
+    // 정규화 좌표(0~1)라 그대로 쓰면 0.123456789 같은 값이 나온다. 세 자리면 충분하다.
+    out.push(kv("핀", `x ${report.pin.x.toFixed(3)} · y ${report.pin.y.toFixed(3)} (0~1 정규화)`));
+  }
+
+  if (report.screenshot) {
+    const bytes = approxBytesOfBase64(report.screenshot.base64);
+    out.push(kv("스크린샷", `${report.screenshot.contentType} · 약 ${humanBytes(bytes)}`));
+  }
+
+  if (c.native) {
+    const n = c.native;
+    out.push(kv("화면 경로", n.screenPath));
+    out.push(kv("내비 스택", n.navPath.length > 0 ? n.navPath.join(" › ") : null));
+    out.push(kv("라우트 파라미터", n.routeParams ? json(n.routeParams) : null));
+    out.push(kv("앱 버전", formatAppInfo(n.appInfo)));
+    out.push(kv("기기", formatDevice(n.device)));
+    out.push(kv("디스플레이", formatDisplay(n.display)));
+  }
+
+  if (c.web) {
+    out.push(kv("뷰포트", formatViewport(c.web.viewport)));
+    out.push(kv("UA", c.web.userAgent));
+  }
+
+  const extra = json(c.extra);
+  out.push(kv("추가", extra));
+
+  // 진단은 "수집 안 함(null)"과 "수집했는데 0건([])"을 구분해서 적는다.
+  // 둘을 똑같이 적으면 읽는 사람이 버그인지 설정인지 판단할 수 없다.
+  if (c.diagnostics === null) {
+    out.push("- 진단: 수집하지 않음");
+  } else {
+    const { network, logs } = c.diagnostics;
+    out.push(`- 진단 네트워크 (${network.length}건)`);
+    for (const e of network) {
+      const status = e.status === null ? "실패" : String(e.status);
+      out.push(`  - ${inline(`${e.method} ${e.url}`)} → ${status} · ${e.durationMs}ms · ${e.at}`);
+    }
+    out.push(`- 진단 로그 (${logs.length}건)`);
+    for (const e of logs) {
+      out.push(`  - [${e.level}] ${inline(e.message)} · ${e.at}`);
+    }
+  }
+
+  return out.filter((line): line is string => line !== null);
+}
+
+/**
+ * 제보 하나를 사람이 읽는 본문으로 만든다.
+ *
+ * 형태: `사용자 코멘트` + 빈 줄 + `접힌 진단 블록 하나`.
+ * 코멘트는 **이스케이프하지 않는다** — 접힌 블록보다 앞에 있어서 우리 블록을 깨뜨릴 수 없고,
+ * 사람이 쓴 문장을 우리가 변형하는 쪽이 더 나쁘다.
+ */
+export function renderReportBody(report: FeedbackReport): string {
+  const comment = report.comment.trim().length > 0 ? report.comment.trimEnd() : "(코멘트 없음)";
+  return [
+    comment,
+    "",
+    DETAILS_OPEN,
+    DETAILS_SUMMARY,
+    "",
+    ...detailLines(report),
+    "",
+    DETAILS_CLOSE,
+  ].join("\n");
+}
+
+/**
+ * 제목. 코멘트 첫 줄을 쓰되, 비어 있으면 종류와 화면으로 대신한다.
+ * 제목이 비면 대상에서 목록이 읽히지 않으므로 항상 비어 있지 않은 문자열을 돌려준다.
+ */
+export function buildTitle(report: FeedbackReport): string {
+  const firstLine = report.comment.split("\n").find((l) => l.trim().length > 0);
+  const fallback = `${KIND_LABEL[report.kind]} — ${
+    report.context.screen ?? report.context.url ?? report.context.app
+  }`;
+  const base = inline(firstLine ?? fallback) || fallback;
+  return base.length > TITLE_MAX_CHARS ? `${base.slice(0, TITLE_MAX_CHARS - 1)}…` : base;
+}

package/src/adapters/index.ts

@@ -0,0 +1,19 @@
+// 어댑터 모음.
+//
+// 코어의 다른 모듈은 이 디렉터리를 **import 하지 않는다.** 방향은 한쪽뿐이다:
+// 어댑터가 코어 타입을 읽고, 코어는 `FeedbackAdapter` 인터페이스만 안다.
+// (코어가 어댑터를 되짚어 import 하는 순간 "어댑터 교체 가능"이 거짓이 된다.)
+
+export { buildTitle, renderReportBody, TITLE_MAX_CHARS } from "./body.js";
+export { buildLinearIssue } from "./linear.js";
+export type { LinearIssueInput } from "./linear.js";
+export { buildNotionPage } from "./notion.js";
+export type { NotionPageInput } from "./notion.js";
+export { buildLassoEnvelope, createLassoAdapter, LASSO_DEFAULT_ENDPOINT } from "./lasso.js";
+export type {
+  LassoAdapterOpts,
+  LassoEnvelope,
+  LassoFetch,
+  LassoRequestInit,
+  LassoResponseLike,
+} from "./lasso.js";

package/src/adapters/lasso.live.test.ts

@@ -0,0 +1,156 @@
+// 라쏘런 어댑터 — **실 엔드포인트 왕복** 테스트.
+//
+// 왜 따로 두나:
+// mock 은 "우리 쪽 조립"만 증명하고 **저쪽이 받아주는지는 증명하지 않는다.**
+// 실제로 이 어댑터의 첫 버전은 필드명을 지어내서(submissionKey/bodyMarkdown/severity…)
+// 실 엔드포인트에 100% 400 으로 거절당했는데, 유닛 테스트 50건은 전부 초록불이었다.
+// 가짜 수집 서버가 같은 잘못된 계약으로 짜여 있었기 때문이다.
+// 400 은 재시도 불가라, 그대로 나갔다면 모든 제보가 조용히 사라졌다.
+//
+// 실행 방법(자격증명이 없으면 skip 된다 — CI 를 막지 않는다):
+//   FEEDBACK_KIT_LIVE_ENDPOINT=https://<...>/dp-agentation-ingest/<sourceId> \
+//   FEEDBACK_KIT_LIVE_TOKEN=dp_ingest_... \
+//   FEEDBACK_KIT_LIVE_ORIGIN=http://localhost:3000 \
+//   pnpm vitest run packages/core/src/adapters/lasso.live.test.ts
+//
+// 배포 전후 1회 돌린다. CI 상시 실행 대상이 아니다(외부 상태에 의존한다).
+
+import { describe, expect, it } from "vitest";
+
+import { buildLassoEnvelope, createLassoAdapter } from "./lasso.js";
+import { uuidv4 } from "../uuid.js";
+import type { FeedbackReport } from "../types.js";
+
+const endpoint = process.env.FEEDBACK_KIT_LIVE_ENDPOINT ?? "";
+const token = process.env.FEEDBACK_KIT_LIVE_TOKEN ?? "";
+const origin = process.env.FEEDBACK_KIT_LIVE_ORIGIN ?? "";
+const live = endpoint !== "" && token !== "" && origin !== "";
+
+/**
+ * 브라우저 흉내내기. `Origin` 은 브라우저가 자동으로 붙이고 스크립트가 못 바꾸는
+ * 헤더라 어댑터가 설정하지 않는다. Node 에서는 아무도 안 붙여서 서버가 403
+ * (origin_not_allowed)을 준다 — 어댑터 잘못이 아니라 실행 환경 차이다.
+ */
+const browserFetch = ((url: string, init: Record<string, unknown>) =>
+  fetch(url, {
+    ...init,
+    headers: { ...(init.headers as Record<string, string>), Origin: origin },
+  } as RequestInit)) as never;
+
+function report(over: Partial<FeedbackReport> = {}): FeedbackReport {
+  return {
+    clientSubmissionId: uuidv4(),
+    kind: "report",
+    comment: "[feedback-kit live] 실 왕복 테스트 — 확인 후 삭제",
+    priority: "normal",
+    screenshot: null,
+    pin: null,
+    element: null,
+    createdAt: new Date().toISOString(),
+    context: {
+      app: "feedback-kit-live",
+      screen: "/live",
+      url: `${origin}/live`,
+      sessionId: "live-session",
+      clientTimestamp: new Date().toISOString(),
+      user: null,
+      // 빌드 플러그인 없이 붙인 앱을 흉내낸다(값은 전부 null 이지만 객체는 있다).
+      source: { screenId: null, sourceFile: null, sourceLine: null },
+      native: null,
+      web: null,
+      diagnostics: null,
+      extra: {},
+    },
+    ...over,
+  } as FeedbackReport;
+}
+
+// 앱 소스 왕복(별도 소스·별도 키). 웹과 계약이 다르다: clientType="app",
+// url 은 app:// 경로, Origin 헤더 없음(브라우저가 아니다).
+const appEndpoint = process.env.FEEDBACK_KIT_LIVE_APP_ENDPOINT ?? "";
+const appToken = process.env.FEEDBACK_KIT_LIVE_APP_TOKEN ?? "";
+const appLive = appEndpoint !== "" && appToken !== "";
+
+describe.skipIf(!appLive)("라쏘런 실 왕복 — 앱", () => {
+  function appReport(): FeedbackReport {
+    const r = report();
+    r.context.platform = "native";
+    r.context.url = null;
+    r.context.screen = "홈";
+    return r;
+  }
+
+  it("앱 제보가 같은 라우트로 받아들여진다", async () => {
+    const adapter = createLassoAdapter({ endpoint: appEndpoint, token: appToken, warn: () => {} });
+
+    const result = await adapter.submit(appReport());
+
+    expect(result.ok, `서버가 거절했다: retryable=${result.retryable}`).toBe(true);
+    expect(result.id).toBeTypeOf("string");
+  });
+
+  it("앱은 url 자리에 화면 경로를 싣는다", () => {
+    const envelope = buildLassoEnvelope(appReport());
+
+    expect(envelope.clientType).toBe("app");
+    // URL 이 없는 플랫폼이라 화면 이름이 그 자리를 대신한다.
+    expect(envelope.url).toBe("app://홈");
+  });
+});
+
+describe.skipIf(!live)("라쏘런 실 왕복", () => {
+  it("리포트 제출이 실제로 받아들여진다(ok:true)", async () => {
+    const adapter = createLassoAdapter({ endpoint, token, fetch: browserFetch, warn: () => {} });
+
+    const result = await adapter.submit(report());
+
+    // 여기서 실패하면 필드명 계약이 어긋난 것이다. 메시지를 그대로 읽어라 —
+    // 서버가 어느 필드를 기대하는지 알려준다.
+    expect(result.ok, `서버가 거절했다: retryable=${result.retryable}`).toBe(true);
+    expect(result.id).toBeTypeOf("string");
+  });
+
+  it("지목 주석도 같은 라우트로 받아들여진다", async () => {
+    const adapter = createLassoAdapter({ endpoint, token, fetch: browserFetch, warn: () => {} });
+
+    const result = await adapter.submit(
+      report({
+        kind: "annotation",
+        pin: { x: 0.5, y: 0.5 },
+        element: {
+          tag: "button",
+          id: "submit",
+          className: "btn",
+          text: "저장",
+          boundingBox: { x: 10, y: 20, width: 80, height: 32 },
+          attributes: {},
+        },
+      })
+    );
+
+    expect(result.ok, `서버가 거절했다: retryable=${result.retryable}`).toBe(true);
+  });
+
+  it("같은 제출 id 를 다시 보내도 서버가 중복으로 접는다", async () => {
+    const adapter = createLassoAdapter({ endpoint, token, fetch: browserFetch, warn: () => {} });
+    const same = report();
+
+    const first = await adapter.submit(same);
+    const second = await adapter.submit(same);
+
+    // 재시도가 제보를 복제하지 않는다는 것 — 큐의 "전송 보장"이 기대는 전제다.
+    expect(first.ok).toBe(true);
+    expect(second.ok).toBe(true);
+    expect(second.id).toBe(first.id);
+  });
+
+  it("잘못된 토큰은 재시도 불가로 끊는다(큐를 막지 않는다)", async () => {
+    const adapter = createLassoAdapter({ endpoint, token: "dp_ingest_wrong", fetch: browserFetch, warn: () => {} });
+
+    const result = await adapter.submit(report());
+
+    expect(result.ok).toBe(false);
+    // 401 을 재시도하면 큐가 영영 안 비워진다.
+    expect(result.retryable).toBe(false);
+  });
+});