@solhun/feedback-kit-core 0.1.0

package/src/diagnostics.ts

@@ -0,0 +1,502 @@
+// 진단 링버퍼 — 호스트 앱의 네트워크 요청과 경고·에러 로그를 모아 제보에 첨부한다.
+//
+// 왜 링버퍼인가: 제보는 "문제가 난 뒤"에 작성된다. 그래서 수집은 항상 켜져 있어야 하고,
+// 메모리는 유한해야 한다. 고정 길이 버퍼에 계속 밀어 넣으면 **직전 N건**이 언제나 남는다.
+//
+// 이 모듈이 지키는 약속(DP-253 진단 컨텍스트 수집):
+// 1. 버퍼는 **모듈 스코프에 두 개**(network 30 / logs 50). 화면마다 상태를 연결할 필요가
+//    없어야 한다 — 어느 화면에서 제보를 열든 같은 버퍼를 본다.
+// 2. 기록 항목은 **메서드·URL·상태코드·소요시간**까지다. `Authorization` 헤더·쿠키·
+//    요청 본문·응답 본문은 **애초에 읽지 않는다**(가리는 게 아니라 접근 자체를 안 한다).
+//    URL 쿼리의 자격증명형 파라미터(`token`, `api_key`, …)와 `user:pass@` 는 값을 가린다.
+// 3. 스냅샷의 두 배열은 **실제로 모은 결과**다. 하드코딩된 빈 배열을 보내지 않는다.
+//    수집이 배선되지 않은 경우는 빈 배열이 아니라 컨텍스트의 `diagnostics` 자체가 null 이다.
+// 4. 원래 동작을 절대 바꾸지 않는다. 래핑된 fetch/XHR/console 은 원본을 그대로 호출하고
+//    결과·예외를 손대지 않고 돌려준다.
+// 5. 위젯 자신의 요청·로그는 캡처에서 제외한다(제보를 보내는 행위가 진단을 오염시키지 않게).
+//    - 요청: `excludeMatcher` 가 true 를 주면 제외(예: 수집 백엔드 URL).
+//    - 로그: 위젯은 `originalConsole` 로 직접 찍어 캡처를 우회한다.
+// 6. 코어는 document/window/react-native 를 직접 참조하지 않는다. 글로벌은 globalThis 로만.
+
+import { RingBuffer } from "./ring-buffer.js";
+import type {
+  DiagLogEntry,
+  DiagNetworkEntry,
+  DiagnosticsExcludeMatcher,
+  DiagnosticsPayload,
+} from "./types.js";
+
+/** 네트워크 링버퍼 용량. 넘치면 오래된 것부터 밀려난다. */
+export const NETWORK_BUFFER_LIMIT = 30;
+
+/** 콘솔 로그(warn/error) 링버퍼 용량. 넘치면 오래된 것부터 밀려난다. */
+export const LOG_BUFFER_LIMIT = 50;
+
+/** 로그 한 건의 최대 길이. 스택 덤프 하나가 버퍼를 통째로 먹는 걸 막는다. */
+export const MAX_LOG_MESSAGE_CHARS = 2000;
+
+export interface DiagnosticsInstallOpts {
+  /** true 를 반환하면 그 요청은 기록하지 않는다(위젯 자신의 전송 등). */
+  excludeMatcher?: DiagnosticsExcludeMatcher;
+  /** 시각 주입(테스트용). */
+  now?: () => number;
+  iso?: (n: number) => string;
+}
+
+/** 최소한의 콘솔 형태. DOM 의 `Console` 타입에 의존하지 않기 위해 구조적으로 정의한다. */
+interface ConsoleLike {
+  warn?: (...a: unknown[]) => void;
+  error?: (...a: unknown[]) => void;
+  log?: (...a: unknown[]) => void;
+}
+
+/**
+ * 진단 수집기. `install()` 로 글로벌을 패치하고 `uninstall()` 로 원복한다.
+ * 생성 자체는 부작용이 없다 — `install()` 을 호출해야 패치가 일어난다.
+ */
+export class DiagnosticsCollector {
+  readonly network: RingBuffer<DiagNetworkEntry>;
+  readonly logs: RingBuffer<DiagLogEntry>;
+
+  private installed = false;
+
+  // 원본 참조(원복용 + 위젯 우회용).
+  private originalFetch: ((...a: unknown[]) => Promise<unknown>) | null = null;
+  private originalXhrOpen: ((...a: unknown[]) => unknown) | null = null;
+  private originalXhrSend: ((...a: unknown[]) => unknown) | null = null;
+  private originalWarn: ((...a: unknown[]) => void) | null = null;
+  private originalError: ((...a: unknown[]) => void) | null = null;
+
+  private excludeMatcher: DiagnosticsExcludeMatcher | null = null;
+  private now: () => number;
+  private iso: (n: number) => string;
+
+  /**
+   * 패치된 fetch 안에서 동기적으로 XHR 이 열리는 깊이.
+   *
+   * React Native 의 `fetch` 는 whatwg-fetch 폴리필이라 내부에서 XMLHttpRequest 를 쓴다.
+   * 둘 다 패치해두면 요청 1건이 2건으로 기록된다. fetch 폴리필은 Promise 실행자 안에서
+   * **동기적으로** `send()` 를 부르므로, 그 구간을 세어 XHR 쪽 기록만 건너뛴다.
+   */
+  private fetchDepth = 0;
+
+  constructor(
+    opts: {
+      now?: () => number;
+      iso?: (n: number) => string;
+      networkLimit?: number;
+      logLimit?: number;
+    } = {}
+  ) {
+    this.now = opts.now ?? ((): number => Date.now());
+    this.iso = opts.iso ?? ((n): string => new Date(n).toISOString());
+    this.network = new RingBuffer<DiagNetworkEntry>(
+      opts.networkLimit ?? NETWORK_BUFFER_LIMIT
+    );
+    this.logs = new RingBuffer<DiagLogEntry>(opts.logLimit ?? LOG_BUFFER_LIMIT);
+  }
+
+  /** 위젯이 자신의 로그를 캡처 없이 찍을 때 쓰는 원본 console. */
+  readonly originalConsole = {
+    warn: (...a: unknown[]): void => {
+      (this.originalWarn ?? consoleMethod("warn"))(...a);
+    },
+    error: (...a: unknown[]): void => {
+      (this.originalError ?? consoleMethod("error"))(...a);
+    },
+    log: (...a: unknown[]): void => {
+      consoleMethod("log")(...a);
+    },
+  };
+
+  /** 글로벌 fetch/XHR/console 을 패치한다. 이미 설치했으면 no-op. */
+  install(opts: DiagnosticsInstallOpts = {}): void {
+    if (this.installed) return;
+    this.installed = true;
+    this.excludeMatcher = opts.excludeMatcher ?? null;
+    if (opts.now) this.now = opts.now;
+    if (opts.iso) this.iso = opts.iso;
+
+    this.patchFetch();
+    this.patchXhr();
+    this.patchConsole();
+  }
+
+  /** 글로벌 패치를 모두 원복한다. 버퍼 내용은 그대로 남는다. */
+  uninstall(): void {
+    if (!this.installed) return;
+    this.installed = false;
+
+    const g = globalThis as Record<string, unknown>;
+
+    if (this.originalFetch) {
+      g.fetch = this.originalFetch;
+      this.originalFetch = null;
+    }
+
+    const XHR = g.XMLHttpRequest as { prototype?: Record<string, unknown> } | undefined;
+    if (XHR?.prototype && this.originalXhrOpen && this.originalXhrSend) {
+      XHR.prototype.open = this.originalXhrOpen;
+      XHR.prototype.send = this.originalXhrSend;
+    }
+    this.originalXhrOpen = null;
+    this.originalXhrSend = null;
+
+    const c = g.console as ConsoleLike | undefined;
+    if (c && this.originalWarn) c.warn = this.originalWarn;
+    if (c && this.originalError) c.error = this.originalError;
+    this.originalWarn = null;
+    this.originalError = null;
+
+    this.excludeMatcher = null;
+    this.fetchDepth = 0;
+  }
+
+  /**
+   * 지금까지 모인 것을 그대로 스냅샷으로 낸다.
+   * 반환 배열은 사본이라 이후 수집이 제보 페이로드를 바꾸지 않는다.
+   */
+  snapshot(): DiagnosticsPayload {
+    return { network: this.network.toArray(), logs: this.logs.toArray() };
+  }
+
+  /** 두 버퍼를 비운다. */
+  clear(): void {
+    this.network.clear();
+    this.logs.clear();
+  }
+
+  // ── 내부: 기록 ────────────────────────────────────────────
+
+  private recordNetwork(
+    method: string,
+    url: string,
+    status: number | null,
+    startedAt: number
+  ): void {
+    this.network.push({
+      method,
+      url,
+      status,
+      durationMs: Math.max(0, Math.round(this.now() - startedAt)),
+      at: this.iso(startedAt),
+    });
+  }
+
+  private recordLog(level: "warn" | "error", args: unknown[]): void {
+    this.logs.push({
+      level,
+      message: safeStringify(args).slice(0, MAX_LOG_MESSAGE_CHARS),
+      at: this.iso(this.now()),
+    });
+  }
+
+  private isExcluded(url: string, method: string): boolean {
+    if (!this.excludeMatcher) return false;
+    try {
+      return this.excludeMatcher({ url, method }) === true;
+    } catch {
+      // 호스트가 준 매처가 던져도 수집을 멈추지 않는다(기록하는 쪽으로 판단).
+      return false;
+    }
+  }
+
+  // ── 내부: 패치 ────────────────────────────────────────────
+
+  private patchFetch(): void {
+    const g = globalThis as Record<string, unknown>;
+    if (typeof g.fetch !== "function") return;
+
+    this.originalFetch = g.fetch as (...a: unknown[]) => Promise<unknown>;
+    const originalFetch = this.originalFetch;
+    const self = this;
+
+    g.fetch = function patchedFetch(
+      input: unknown,
+      // init 은 `method` 만 읽는다. headers/body 는 **의도적으로 건드리지 않는다**.
+      init?: { method?: string }
+    ): Promise<unknown> {
+      const { url, method } = describeRequest(input, init);
+      const excluded = self.isExcluded(url, method);
+      const start = self.now();
+
+      let pending: Promise<unknown>;
+      self.fetchDepth += 1;
+      try {
+        pending = Promise.resolve(originalFetch(input, init));
+      } catch (err) {
+        // 동기 throw 도 실패 1건으로 남기고 그대로 전파한다.
+        self.fetchDepth -= 1;
+        if (!excluded) self.recordNetwork(method, url, null, start);
+        throw err;
+      }
+      self.fetchDepth -= 1;
+
+      return pending.then(
+        (raw: unknown) => {
+          if (!excluded) {
+            const status = (raw as { status?: unknown } | null)?.status;
+            self.recordNetwork(
+              method,
+              url,
+              typeof status === "number" ? status : null,
+              start
+            );
+          }
+          return raw;
+        },
+        (err: unknown) => {
+          if (!excluded) self.recordNetwork(method, url, null, start);
+          throw err;
+        }
+      );
+    };
+  }
+
+  private patchXhr(): void {
+    const g = globalThis as Record<string, unknown>;
+    const XHR = g.XMLHttpRequest as
+      | { prototype?: Record<string, unknown> }
+      | undefined;
+    if (typeof g.XMLHttpRequest !== "function" || !XHR?.prototype) return;
+
+    const proto = XHR.prototype;
+    if (typeof proto.open !== "function" || typeof proto.send !== "function") return;
+
+    this.originalXhrOpen = proto.open as (...a: unknown[]) => unknown;
+    this.originalXhrSend = proto.send as (...a: unknown[]) => unknown;
+    const oOpen = this.originalXhrOpen;
+    const oSend = this.originalXhrSend;
+    const self = this;
+
+    proto.open = function patchedOpen(
+      method: unknown,
+      url: unknown,
+      ...rest: unknown[]
+    ): unknown {
+      // 인스턴스에 메타를 저장해 send/loadend 에서 쓴다.
+      (this as Record<string, unknown>).__fk_meta = {
+        method: String(method ?? "GET").toUpperCase(),
+        url: sanitizeUrl(String(url ?? "")),
+      };
+      return oOpen.call(this, method, url, ...rest);
+    };
+
+    // send 의 인자는 요청 본문이다 — 읽지 않고 원본에 그대로 넘기기만 한다.
+    proto.send = function patchedSend(...args: unknown[]): unknown {
+      const meta = (this as Record<string, unknown>).__fk_meta as
+        | { method: string; url: string }
+        | undefined;
+      const viaFetch = self.fetchDepth > 0;
+      const addEv = (this as {
+        addEventListener?: (t: string, cb: () => void) => void;
+      }).addEventListener;
+
+      if (meta && !viaFetch && typeof addEv === "function") {
+        const excluded = self.isExcluded(meta.url, meta.method);
+        const start = self.now();
+        let recorded = false;
+        // loadend 는 성공·실패·중단 모두에서 발생한다. 한 번만 기록한다.
+        addEv.call(this, "loadend", () => {
+          if (recorded || excluded) return;
+          recorded = true;
+          const status = (this as { status?: unknown }).status;
+          // XHR 은 실패 시 status 0 을 준다 — "응답 못 받음"이므로 null 로 남긴다.
+          self.recordNetwork(
+            meta.method,
+            meta.url,
+            typeof status === "number" && status > 0 ? status : null,
+            start
+          );
+        });
+      }
+
+      return oSend.apply(this, args);
+    };
+  }
+
+  private patchConsole(): void {
+    const c = (globalThis as { console?: ConsoleLike }).console;
+    if (!c) return;
+    const self = this;
+
+    if (typeof c.warn === "function") {
+      const orig = c.warn.bind(c) as (...a: unknown[]) => void;
+      this.originalWarn = orig;
+      c.warn = function patchedWarn(...args: unknown[]): void {
+        self.recordLog("warn", args);
+        orig(...args);
+      };
+    }
+    if (typeof c.error === "function") {
+      const orig = c.error.bind(c) as (...a: unknown[]) => void;
+      this.originalError = orig;
+      c.error = function patchedError(...args: unknown[]): void {
+        self.recordLog("error", args);
+        orig(...args);
+      };
+    }
+  }
+}
+
+/**
+ * 모듈 스코프 공유 수집기.
+ *
+ * 화면·컴포넌트마다 수집기를 연결할 필요가 없어야 한다는 요구사항 때문에 여기 하나를 둔다.
+ * 위젯이 어느 화면에서 열리든 이 인스턴스의 스냅샷을 싣는다.
+ */
+export const sharedDiagnostics = new DiagnosticsCollector();
+
+// ────────────────────────────────────────────────────────────────────────────
+// 헬퍼
+// ────────────────────────────────────────────────────────────────────────────
+
+function consoleMethod(name: "warn" | "error" | "log"): (...a: unknown[]) => void {
+  return (...a: unknown[]): void => {
+    const c = (globalThis as { console?: ConsoleLike }).console;
+    c?.[name]?.(...a);
+  };
+}
+
+function safeStringify(args: unknown[]): string {
+  // 인자들을 사람이 읽을 수 있는 한 줄 문자열로. 직렬화 실패는 toString 으로.
+  return args
+    .map((a) => {
+      if (typeof a === "string") return a;
+      if (a instanceof Error) return `${a.name}: ${a.message}`;
+      try {
+        return JSON.stringify(a) ?? String(a);
+      } catch {
+        try {
+          return String(a);
+        } catch {
+          return "[unserializable]";
+        }
+      }
+    })
+    .join(" ");
+}
+
+/**
+ * 요청에서 **메서드와 URL만** 뽑는다.
+ *
+ * `init.headers` / `init.body` 는 읽지 않는다. Request 객체가 와도 `url`·`method` 만
+ * 본다 — 그래야 `Authorization` 헤더나 본문이 실수로도 버퍼에 닿지 않는다.
+ */
+function describeRequest(
+  input: unknown,
+  init?: { method?: string }
+): { url: string; method: string } {
+  let url = "";
+  let method = "GET";
+
+  if (typeof input === "string") {
+    url = input;
+  } else if (input && typeof input === "object") {
+    const maybeUrl = (input as { url?: unknown }).url;
+    const maybeHref = (input as { href?: unknown }).href;
+    if (typeof maybeUrl === "string") url = maybeUrl;
+    else if (typeof maybeHref === "string") url = maybeHref;
+    else {
+      try {
+        url = String(input);
+      } catch {
+        url = "";
+      }
+    }
+    const maybeMethod = (input as { method?: unknown }).method;
+    if (typeof maybeMethod === "string") method = maybeMethod;
+  }
+
+  if (init && typeof init.method === "string") method = init.method;
+
+  return { url: sanitizeUrl(url), method: method.toUpperCase() };
+}
+
+/** 값을 가려야 하는 쿼리 파라미터 이름(정규화 후 비교). */
+const CREDENTIAL_PARAMS = new Set([
+  "accesskey",
+  "accesstoken",
+  "apikey",
+  "apisecret",
+  "auth",
+  "authorization",
+  "authtoken",
+  "clientsecret",
+  "code",
+  "credential",
+  "credentials",
+  "idtoken",
+  "jwt",
+  "key",
+  "password",
+  "passwd",
+  "privatekey",
+  "pwd",
+  "refreshtoken",
+  "secret",
+  "secretkey",
+  "session",
+  "sessionid",
+  "sessiontoken",
+  "sid",
+  "sig",
+  "signature",
+  "token",
+]);
+
+/** 가려진 값 표시. 파라미터가 "있었다"는 사실은 남기고 값만 지운다. */
+export const REDACTED = "REDACTED";
+
+function isCredentialParam(rawName: string): boolean {
+  const name = rawName.toLowerCase().replace(/[-_.]/g, "");
+  if (CREDENTIAL_PARAMS.has(name)) return true;
+  return (
+    name.endsWith("token") ||
+    name.endsWith("secret") ||
+    name.endsWith("password") ||
+    name.endsWith("apikey")
+  );
+}
+
+/**
+ * URL 에서 자격증명을 걷어낸다.
+ * - `#fragment` 는 통째로 버린다(진단 가치는 없고 토큰이 실리는 경우가 있다).
+ * - `scheme://user:pass@host` 의 userinfo 를 지운다.
+ * - 자격증명형 쿼리 파라미터의 **값만** `REDACTED` 로 바꾼다.
+ */
+export function sanitizeUrl(raw: string): string {
+  if (!raw) return "";
+
+  const hashAt = raw.indexOf("#");
+  const withoutHash = hashAt >= 0 ? raw.slice(0, hashAt) : raw;
+
+  const queryAt = withoutHash.indexOf("?");
+  const base = stripUserInfo(
+    queryAt >= 0 ? withoutHash.slice(0, queryAt) : withoutHash
+  );
+  if (queryAt < 0) return base;
+
+  const query = withoutHash.slice(queryAt + 1);
+  if (query.length === 0) return base;
+
+  const parts = query.split("&").map((pair) => {
+    const eq = pair.indexOf("=");
+    if (eq < 0) return pair;
+    const name = pair.slice(0, eq);
+    return isCredentialParam(name) ? `${name}=${REDACTED}` : pair;
+  });
+  return `${base}?${parts.join("&")}`;
+}
+
+function stripUserInfo(url: string): string {
+  const schemeAt = url.indexOf("://");
+  if (schemeAt < 0) return url;
+  const authorityStart = schemeAt + 3;
+  const pathAt = url.indexOf("/", authorityStart);
+  const authority = pathAt < 0 ? url.slice(authorityStart) : url.slice(authorityStart, pathAt);
+  const at = authority.lastIndexOf("@");
+  if (at < 0) return url;
+  const cleaned = authority.slice(at + 1);
+  return url.slice(0, authorityStart) + cleaned + (pathAt < 0 ? "" : url.slice(pathAt));
+}

package/src/guest-id.ts

@@ -0,0 +1,36 @@
+// 게스트 영구 식별자 — getUser prop이 없을 때 사용.
+//
+// 요구사항(TC3): getUser가 없으면 게스트로 취급하되, 식별자는 영구적이어야 한다.
+// 즉 같은 저장소(localStorage/AsyncStorage)를 쓰는 한, 위젯을 다시 띄워도 같은 게스트 ID.
+// 그래서 최초 1회 생성해 저장소에 넣고, 이후엔 그 값을 재사용한다.
+
+import type { FeedbackStorage, FeedbackUser } from "./types.js";
+import { uuidv4 } from "./uuid.js";
+
+const GUEST_KEY = "feedback-kit:guest-id";
+
+/**
+ * 저장소에서 게스트 id를 찾아 반환하고, 없으면 새로 만들어 저장한다.
+ * 반환값은 사용자가 "이미 알고 있던" 식별자이므로 멱등(같은 저장소 → 같은 id).
+ */
+export async function getOrCreateGuestId(
+  storage: FeedbackStorage
+): Promise<string> {
+  const existing = await storage.get(GUEST_KEY);
+  if (existing && existing.length > 0) {
+    return existing;
+  }
+  const id = `guest_${uuidv4()}`;
+  await storage.set(GUEST_KEY, id);
+  return id;
+}
+
+/**
+ * 게스트 id로 FeedbackUser 객체를 만든다.
+ *
+ * `isGuest: true` 를 반드시 붙인다. 게스트를 `user: null` 로 보내면 받는 쪽에서
+ * "신원 수집이 안 된 제보"와 "게스트가 남긴 제보"를 구분할 수 없다.
+ */
+export function guestUser(id: string): FeedbackUser {
+  return { id, isGuest: true };
+}