@solhun/feedback-kit-core 0.1.0

package/src/config.ts

@@ -0,0 +1,396 @@
+// 설정과 토큰 — 붙이는 데 필요한 것을 한 줄로 줄인다.
+//
+//     <FeedbackKit token={TOKEN} />
+//
+// 위 한 줄이 성립하려면 나머지 항목이 **전부 기본값을 갖고 있어야** 한다. 그래서 이
+// 모듈의 본체는 `resolveConfig` 하나이고, 나머지는 그 결과를 읽는 판정 함수들이다.
+//
+// ## 수집 토큰은 비밀이 아니다
+//
+// 토큰은 클라이언트 번들에 **상수로 인라인**된다(웹 `VITE_*`/`NEXT_PUBLIC_*`, 앱
+// `EXPO_PUBLIC_*`). 누구나 번들을 열어 꺼낼 수 있으므로 토큰 자체는 접근 제어가 아니다.
+// 실제 방어선은 서버에 있다 — 웹은 등록된 Origin 에서 온 요청만 받고, 앱은 Origin 검사가
+// 불가능하므로 시간당 한도가 방어선이다.
+//
+// 이 사실을 코드 주석과 문서에 남기는 이유는, 토큰이 노출됐을 때 "유출 사고"로 오인해
+// 전면 회전 같은 과잉 대응을 하는 걸 막기 위해서다. 저장소에 커밋하지 않는 것은
+// **위생 문제이지 보안 경계가 아니다.**
+//
+// 또 하나: 환경변수는 빌드 타임에 인라인되므로 값을 바꾸면 **다시 빌드해야** 반영된다.
+// 앱은 OTA 로 반영되지 않는다. 그래서 아래 `resolveConfig` 는 치환되지 않은 환경변수
+// 문자열(`undefined`, `import.meta.env.VITE_TOKEN` 등)을 토큰으로 받으면 경고를 남긴다.
+// 이건 실제로 가장 자주 나는 사고이고, 조용히 미귀속으로 흘러가면 알아채기 어렵다.
+
+import type { ContextUser, DiagnosticsPayload, FeedbackAdapter, FeedbackUser } from "./types.js";
+
+// ────────────────────────────────────────────────────────────────────────────
+// 노출 범위
+// ────────────────────────────────────────────────────────────────────────────
+
+/** 노출 판정에 쓰이는 현재 상황. 함수형 `visibility` 가 그대로 받는다. */
+export interface VisibilityEnv {
+  /** 현재 사용자. 로그인 전이면 게스트이거나 null. */
+  user: ContextUser | FeedbackUser | null;
+  /** 개발 빌드 여부. */
+  isDev: boolean;
+  platform: "web" | "native" | "unknown";
+}
+
+/** 프로젝트가 직접 판정하는 형태. true 면 노출. */
+export type VisibilityFn = (env: VisibilityEnv) => boolean;
+
+/**
+ * 누구에게 위젯을 노출할지.
+ *
+ * 기본값은 `all` 이다. 실사용자 제보가 실제로 가치를 냈기 때문에 패키지가 먼저 막지
+ * 않는다. 좁혀야 하는 프로젝트가 `internal`·`dev-only`·함수로 좁힌다.
+ */
+export type Visibility = "all" | "internal" | "dev-only" | VisibilityFn;
+
+const VISIBILITY_KEYWORDS = ["all", "internal", "dev-only"] as const;
+
+/** `internal` 판정의 기본 근거. 프로젝트가 `internalRoles` 로 갈아끼운다. */
+export const DEFAULT_INTERNAL_ROLES: readonly string[] = ["internal", "admin", "staff"];
+
+// ────────────────────────────────────────────────────────────────────────────
+// 위치 / 어댑터
+// ────────────────────────────────────────────────────────────────────────────
+
+export type WidgetCorner = "bottom-right" | "bottom-left" | "top-right" | "top-left";
+
+const CORNERS: readonly WidgetCorner[] = [
+  "bottom-right",
+  "bottom-left",
+  "top-right",
+  "top-left",
+];
+
+export interface WidgetPosition {
+  corner: WidgetCorner;
+  /** 모서리로부터의 가로 여백(px). */
+  offsetX: number;
+  /** 모서리로부터의 세로 여백(px). */
+  offsetY: number;
+}
+
+export const DEFAULT_POSITION: WidgetPosition = {
+  corner: "bottom-right",
+  offsetX: 16,
+  offsetY: 16,
+};
+
+/** 내장 어댑터 이름. 실제 구현과 전송 규약은 어댑터 섹션이 갖는다. */
+export type AdapterName = "lasso" | "linear" | "notion";
+
+const ADAPTER_NAMES: readonly AdapterName[] = ["lasso", "linear", "notion"];
+
+export const DEFAULT_ADAPTER: AdapterName = "lasso";
+
+/**
+ * 수집 엔드포인트 기본값은 **어댑터가 갖는다.**
+ *
+ * 코어가 특정 백엔드 URL 을 상수로 들고 있으면 어댑터 교체가 무의미해지고, 코어가
+ * 어댑터별 사정을 아는 셈이 된다. 그래서 여기서는 "지정 안 함"을 `null` 로 표현하고,
+ * 어댑터가 자기 내장 기본값을 쓰도록 넘긴다.
+ */
+export const ENDPOINT_FROM_ADAPTER = null;
+
+// ────────────────────────────────────────────────────────────────────────────
+// 경고
+// ────────────────────────────────────────────────────────────────────────────
+
+export type ConfigWarningCode =
+  /** 토큰이 없다 — 전송은 되지만 미귀속이다. */
+  | "missing-token"
+  /** 환경변수가 치환되지 않은 채로 들어왔다(빌드 설정 사고). */
+  | "unsubstituted-token"
+  /** 모르는 어댑터 이름 — 기본 어댑터로 되돌린다. */
+  | "unknown-adapter"
+  /** 모르는 visibility 값 — `all` 로 되돌린다. */
+  | "unknown-visibility"
+  /** 모르는 위치 값 — 우하단으로 되돌린다. */
+  | "unknown-position"
+  /** 사용자가 준 판정 함수가 예외를 던졌다 — 숨김으로 처리한다. */
+  | "visibility-threw";
+
+export interface ConfigWarning {
+  code: ConfigWarningCode;
+  message: string;
+}
+
+/**
+ * 치환되지 않은 환경변수처럼 보이는 값.
+ *
+ * `EXPO_PUBLIC_` 접두사를 빠뜨리거나 `.env` 를 안 만들면 번들에 `undefined` 라는
+ * **문자열**이 그대로 박히는 일이 흔하다. 눈으로는 토큰이 있는 것처럼 보이는데 서버는
+ * 미귀속으로 받는다.
+ */
+function looksUnsubstituted(token: string): boolean {
+  const t = token.trim();
+  if (t === "undefined" || t === "null" || t === "NaN") return true;
+  if (t.includes("process.env.") || t.includes("import.meta.env")) return true;
+  // `${VITE_TOKEN}` / `%NEXT_PUBLIC_TOKEN%` 같은 미치환 플레이스홀더.
+  if (/^\$\{.*\}$/.test(t) || /^%.*%$/.test(t)) return true;
+  return false;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// 설정
+// ────────────────────────────────────────────────────────────────────────────
+
+export interface FeedbackConfig {
+  /** 수집 토큰. 없으면 미귀속으로 전송된다(막지 않는다). */
+  token?: string | null;
+  /** 수집 엔드포인트. 없으면 어댑터 내장 기본값. */
+  endpoint?: string | null;
+  /** 어댑터 이름 또는 어댑터 구현체. */
+  adapter?: AdapterName | FeedbackAdapter;
+  /** 노출 범위. 기본 `all`. */
+  visibility?: Visibility;
+  /** 모달을 열 때 화면을 자동 캡처할지. */
+  captureScreenshot?: boolean;
+  /** network·logs 링버퍼를 수집할지. false 면 아예 설치하지 않는다. */
+  captureDiagnostics?: boolean;
+  /** 플로팅 버튼 위치. 모서리만 주면 여백은 기본값. */
+  position?: WidgetCorner | Partial<WidgetPosition>;
+  /** `internal` 판정을 프로젝트가 직접 할 때. 주면 `internalRoles` 보다 우선한다. */
+  isInternal?: VisibilityFn;
+  /** `internal` 로 볼 역할 목록. 기본 {@link DEFAULT_INTERNAL_ROLES}. */
+  internalRoles?: readonly string[];
+  /** 개발 빌드 여부. 안 주면 런타임 전역에서 추론한다. */
+  isDev?: boolean;
+  /** 경고 출구. 안 주면 `resolveConfig` 결과의 `warnings` 로만 남는다. */
+  onWarn?: (warning: ConfigWarning) => void;
+}
+
+/** 기본값이 모두 채워진 설정. 위젯은 이것만 본다. */
+export interface ResolvedConfig {
+  token: string | null;
+  endpoint: string | null;
+  adapter: AdapterName | FeedbackAdapter;
+  visibility: Visibility;
+  captureScreenshot: boolean;
+  captureDiagnostics: boolean;
+  position: WidgetPosition;
+  isInternal: VisibilityFn | null;
+  internalRoles: readonly string[];
+  isDev: boolean;
+  warnings: ConfigWarning[];
+}
+
+/**
+ * 개발 빌드 여부 추론.
+ *
+ * 코어는 플랫폼 무관이라 `__DEV__`(RN)·`process.env.NODE_ENV`(웹/노드)를 **globalThis
+ * 를 통해서만** 본다. 어느 쪽도 없으면 프로덕션으로 본다 — 모르는 상태에서 개발 빌드로
+ * 단정하면 `dev-only` 가 실사용자에게 새기 때문이다.
+ */
+export function detectDevBuild(): boolean {
+  const g = globalThis as Record<string, unknown>;
+  if (typeof g.__DEV__ === "boolean") return g.__DEV__;
+  const proc = g.process as { env?: Record<string, string | undefined> } | undefined;
+  const nodeEnv = proc?.env?.NODE_ENV;
+  if (typeof nodeEnv === "string") return nodeEnv !== "production";
+  return false;
+}
+
+function normalizePosition(
+  input: FeedbackConfig["position"],
+  warn: (code: ConfigWarningCode, message: string) => void
+): WidgetPosition {
+  if (input === undefined || input === null) return { ...DEFAULT_POSITION };
+
+  if (typeof input === "string") {
+    if (CORNERS.includes(input)) {
+      return { ...DEFAULT_POSITION, corner: input };
+    }
+    warn("unknown-position", `모르는 position "${input}" — 우하단으로 되돌린다.`);
+    return { ...DEFAULT_POSITION };
+  }
+
+  const corner =
+    input.corner !== undefined && CORNERS.includes(input.corner)
+      ? input.corner
+      : DEFAULT_POSITION.corner;
+  if (input.corner !== undefined && !CORNERS.includes(input.corner)) {
+    warn("unknown-position", `모르는 position.corner "${String(input.corner)}" — 우하단으로 되돌린다.`);
+  }
+  return {
+    corner,
+    offsetX: numberOr(input.offsetX, DEFAULT_POSITION.offsetX),
+    offsetY: numberOr(input.offsetY, DEFAULT_POSITION.offsetY),
+  };
+}
+
+function numberOr(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+function normalizeAdapter(
+  input: FeedbackConfig["adapter"],
+  warn: (code: ConfigWarningCode, message: string) => void
+): AdapterName | FeedbackAdapter {
+  if (input === undefined || input === null) return DEFAULT_ADAPTER;
+  // 구현체를 직접 준 경우 — 이름 검사 대상이 아니다.
+  if (typeof input === "object") return input;
+  if (ADAPTER_NAMES.includes(input)) return input;
+  warn("unknown-adapter", `모르는 어댑터 "${String(input)}" — "${DEFAULT_ADAPTER}" 로 되돌린다.`);
+  return DEFAULT_ADAPTER;
+}
+
+function normalizeVisibility(
+  input: FeedbackConfig["visibility"],
+  warn: (code: ConfigWarningCode, message: string) => void
+): Visibility {
+  if (input === undefined || input === null) return "all";
+  if (typeof input === "function") return input;
+  if ((VISIBILITY_KEYWORDS as readonly string[]).includes(input)) return input;
+  warn("unknown-visibility", `모르는 visibility "${String(input)}" — "all" 로 되돌린다.`);
+  return "all";
+}
+
+function normalizeToken(
+  input: FeedbackConfig["token"],
+  warn: (code: ConfigWarningCode, message: string) => void
+): string | null {
+  const token = typeof input === "string" ? input.trim() : "";
+  if (token === "") {
+    warn(
+      "missing-token",
+      "수집 토큰이 없다 — 제보는 그대로 전송되지만 프로젝트에 귀속되지 않는다."
+    );
+    return null;
+  }
+  if (looksUnsubstituted(token)) {
+    warn(
+      "unsubstituted-token",
+      `토큰이 환경변수 치환 전 값으로 보인다("${token}"). 환경변수는 빌드 타임에 인라인되므로 ` +
+        "값을 넣은 뒤 다시 빌드해야 하고, 앱은 OTA 로 반영되지 않는다."
+    );
+    return null;
+  }
+  return token;
+}
+
+/**
+ * 부분 설정을 기본값으로 채운다.
+ *
+ * **던지지 않는다.** 설정이 틀렸다고 위젯이 호스트 앱을 깨거나 사용자 화면에 오류를
+ * 띄우면, 붙이는 비용이 한 줄이라는 전제가 무너진다. 모르는 값은 기본값으로 되돌리고
+ * 경고만 남긴다.
+ */
+export function resolveConfig(config: FeedbackConfig = {}): ResolvedConfig {
+  const warnings: ConfigWarning[] = [];
+  const warn = (code: ConfigWarningCode, message: string): void => {
+    const warning: ConfigWarning = { code, message };
+    warnings.push(warning);
+    // 호스트가 준 출구도 깨질 수 있다 — 경고 때문에 설정 해석이 실패하면 안 된다.
+    try {
+      config.onWarn?.(warning);
+    } catch {
+      /* 무시 */
+    }
+  };
+
+  const endpoint = typeof config.endpoint === "string" && config.endpoint.trim() !== ""
+    ? config.endpoint.trim()
+    : ENDPOINT_FROM_ADAPTER;
+
+  return {
+    token: normalizeToken(config.token, warn),
+    endpoint,
+    adapter: normalizeAdapter(config.adapter, warn),
+    visibility: normalizeVisibility(config.visibility, warn),
+    captureScreenshot: config.captureScreenshot ?? true,
+    captureDiagnostics: config.captureDiagnostics ?? true,
+    position: normalizePosition(config.position, warn),
+    isInternal: typeof config.isInternal === "function" ? config.isInternal : null,
+    internalRoles: config.internalRoles ?? DEFAULT_INTERNAL_ROLES,
+    isDev: config.isDev ?? detectDevBuild(),
+    warnings,
+  };
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// 노출 판정
+// ────────────────────────────────────────────────────────────────────────────
+
+export function isInternalUser(resolved: ResolvedConfig, env: VisibilityEnv): boolean {
+  if (resolved.isInternal) return resolved.isInternal(env) === true;
+
+  const user = env.user;
+  if (!user) return false;
+  // 게스트는 내부 계정일 수 없다.
+  if (user.isGuest === true) return false;
+  const role = typeof user.role === "string" ? user.role.toLowerCase() : null;
+  if (role === null) return false;
+  return resolved.internalRoles.some((r) => r.toLowerCase() === role);
+}
+
+/**
+ * 지금 이 사용자에게 플로팅 버튼을 보여줄지.
+ *
+ * 판정에 실패하면(사용자가 준 함수가 던지면) **숨긴다.** 노출 범위를 좁힌 프로젝트가
+ * 있다는 건 보이면 안 되는 이유가 있다는 뜻이므로, 애매할 때 새는 쪽보다 안 보이는
+ * 쪽이 안전하다.
+ */
+export function shouldShowWidget(
+  resolved: ResolvedConfig,
+  input: Partial<VisibilityEnv> = {}
+): boolean {
+  const env: VisibilityEnv = {
+    user: input.user ?? null,
+    isDev: input.isDev ?? resolved.isDev,
+    platform: input.platform ?? "unknown",
+  };
+
+  const visibility = resolved.visibility;
+  // `isInternal` 도 사용자가 준 함수라, 판정 전체를 한 번에 감싼다.
+  try {
+    if (typeof visibility === "function") return visibility(env) === true;
+
+    switch (visibility) {
+      case "all":
+        return true;
+      case "dev-only":
+        return env.isDev;
+      case "internal":
+        return isInternalUser(resolved, env);
+      default:
+        return true;
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    resolved.warnings.push({
+      code: "visibility-threw",
+      message: `visibility 판정 함수가 실패해 위젯을 숨긴다: ${message}`,
+    });
+    return false;
+  }
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// 진단 수집 배선
+// ────────────────────────────────────────────────────────────────────────────
+
+/** `DiagnosticsCollector` 중 설정 배선에 필요한 최소 형태. */
+export interface DiagnosticsSource {
+  install(): void;
+  snapshot(): DiagnosticsPayload;
+}
+
+/**
+ * `captureDiagnostics` 를 실제 배선으로 옮긴다.
+ *
+ * 꺼져 있으면 **공급자를 만들지 않고 수집기도 설치하지 않는다.** 빈 배열을 상수로
+ * 돌려주는 공급자를 만들면 "수집했는데 아무 일도 없었다"와 "애초에 수집하지 않았다"가
+ * 구분되지 않는다. 공급자가 없으면 `buildContext` 가 `diagnostics: null` 을 쓴다.
+ */
+export function diagnosticsProviderFor(
+  resolved: Pick<ResolvedConfig, "captureDiagnostics">,
+  collector: DiagnosticsSource
+): (() => DiagnosticsPayload) | undefined {
+  if (!resolved.captureDiagnostics) return undefined;
+  collector.install();
+  return () => collector.snapshot();
+}