@solhun/feedback-kit-core 0.1.0

package/src/context.ts

@@ -0,0 +1,326 @@
+// 제보 컨텍스트 조립 — "이 제보가 어디서, 누가, 어떤 상태에서 났는가"를 모은다.
+//
+// 왜 report.ts 에서 분리했나: 컨텍스트 수집은 플랫폼 공급자(앱 정보·기기·디스플레이·
+// 진단 버퍼)를 여러 개 받는다. 제보 조립(report.ts)은 그 결과를 쓰기만 한다.
+//
+// 설계 원칙:
+// - 코어는 여전히 플랫폼 무관이다. `expo-constants` 같은 걸 import 하지 않고,
+//   **함수 공급자를 주입받아** 호출만 한다. 앱/웹 패키지가 그 공급자를 채운다.
+// - 공급자가 던지거나 이상한 값을 줘도 제보를 잃지 않는다. 각 항목은 독립적으로
+//   실패하고 그 자리만 null 이 된다.
+// - "값이 없다"와 "수집이 배선되지 않았다"를 구분한다. 공급자가 아예 없으면
+//   해당 블록(`native`/`web`/`diagnostics`)이 통째로 null 이고, 공급자는 있는데
+//   값을 못 구했으면 블록은 있고 그 안의 필드가 null 이다.
+
+import { getOrCreateGuestId } from "./guest-id.js";
+import type {
+  AppInfo,
+  ContextUser,
+  DeviceInfo,
+  DiagnosticsPayload,
+  DisplayInfo,
+  FeedbackContext,
+  FeedbackStorage,
+  FeedbackUser,
+  GetCurrentScreenFn,
+  GetUserFn,
+  NativeContext,
+  SourceMapping,
+  WebContext,
+} from "./types.js";
+
+/**
+ * 웹 공급자가 돌려주는 원자료.
+ * 모든 칸이 선택이다 — 못 구한 값은 빼면 되고, 코어가 null 로 채운다.
+ */
+export interface WebContextInput {
+  viewport?: {
+    width?: number | null;
+    height?: number | null;
+    devicePixelRatio?: number | null;
+  };
+  userAgent?: string | null;
+}
+
+/** 앱/웹 컨텍스트를 채우는 공급자 묶음. 전부 선택이다. */
+export interface ContextProviders {
+  /** 현재 URL(웹) 또는 딥링크(앱). */
+  getUrl?: () => string | null;
+  /** 라우트 스택. 바깥(루트)부터 안쪽(현재 화면) 순서. */
+  getNavPath?: () => string[] | null;
+  /** 현재 화면 파라미터 원본. JSON 왕복으로 정제해서 싣는다. */
+  getRouteParams?: () => unknown;
+  /** 앱 빌드 정보(version/channel/updateId/runtimeVersion). */
+  getAppInfo?: () => Partial<AppInfo> | null;
+  /** 기기 정보(model/osName/osVersion/deviceType). */
+  getDevice?: () => Partial<DeviceInfo> | null;
+  /** 화면 크기·배율(width/height/pixelRatio/fontScale). */
+  getDisplay?: () => Partial<DisplayInfo> | null;
+  /** 웹 뷰포트·userAgent. */
+  getWebContext?: () => WebContextInput | null;
+  /**
+   * 진단 스냅샷 공급자.
+   * 주지 않으면 `diagnostics` 는 **빈 배열이 아니라 null** 이다
+   * (수집이 배선되지 않았다는 뜻과 "그 세션에 아무 일도 없었다"는 뜻을 구분한다).
+   */
+  getDiagnostics?: () => DiagnosticsPayload | null;
+  /** 화면 이름 → 소스 파일 경로. 빌드 플러그인이 생성한다. 없으면 screenPath: null. */
+  screenSourceMap?: Record<string, string> | null;
+  /** 타임존 결정(테스트 주입용). 없으면 Intl 로 알아낸다. */
+  getTimezone?: () => string | null;
+}
+
+export interface BuildContextOpts extends ContextProviders {
+  app: string;
+  sessionId: string;
+  storage: FeedbackStorage;
+  platform: FeedbackContext["platform"];
+  /** 제출 시점 사용자 결정. 없으면 게스트. */
+  getUser?: GetUserFn;
+  /** 현재 화면 이름. 없거나 null 반환 → screen: null. */
+  getCurrentScreen?: GetCurrentScreenFn;
+  /** 빌드 플러그인 매핑. 없으면 screenId/sourceFile 이 null. */
+  source?: SourceMapping;
+  /** 자유 메타. 기본 {}. */
+  extra?: Record<string, unknown>;
+  /** 시간 주입(테스트용). */
+  now?: () => number;
+  iso?: (n: number) => string;
+}
+
+/**
+ * getUser prop을 **제출 시점에** 호출해 사용자를 결정한다(캐싱하지 않는다).
+ * - getUser 없음 → 게스트(기기에 영구 저장된 id).
+ * - getUser 는 있지만 빈 결과/예외 → 게스트 폴백(제보 자체는 잃지 않는다).
+ * - getUser 결과에 id 있음 → 그대로 사용.
+ *
+ * 게스트도 `isGuest: true` 로 **객체를 채운다**. 반환이 null 인 경우는 저장소 접근이
+ * 실패해 게스트 식별자조차 만들지 못한 최초 실행 순간뿐이다.
+ */
+export async function resolveContextUser(
+  getUser: GetUserFn | undefined,
+  storage: FeedbackStorage
+): Promise<ContextUser | null> {
+  if (typeof getUser === "function") {
+    try {
+      const u = await Promise.resolve(getUser());
+      if (u && typeof u.id === "string" && u.id.length > 0) {
+        return normalizeUser(u);
+      }
+    } catch {
+      // getUser 가 던지면 게스트로 폴백한다.
+    }
+  }
+  try {
+    const id = await getOrCreateGuestId(storage);
+    return { id, email: null, isGuest: true };
+  } catch {
+    // 저장소를 읽지도 쓰지도 못한 상태 — 신원을 만들 수 없다.
+    return null;
+  }
+}
+
+/** 호스트가 준 FeedbackUser 를 제보에 실리는 ContextUser 로 정규화한다. */
+export function normalizeUser(u: FeedbackUser): ContextUser {
+  const out: ContextUser = {
+    id: u.id,
+    email: typeof u.email === "string" ? u.email : null,
+    // isGuest 생략 = 로그인 사용자.
+    isGuest: u.isGuest === true,
+  };
+  if (typeof u.name === "string") out.name = u.name;
+  if (typeof u.role === "string") out.role = u.role;
+  return out;
+}
+
+/** FeedbackReport.context 를 조립한다. 사용자·화면·기기·진단 수집을 모두 포함. */
+export async function buildContext(
+  opts: BuildContextOpts
+): Promise<FeedbackContext> {
+  const now = opts.now ?? ((): number => Date.now());
+  const iso = opts.iso ?? ((n: number): string => new Date(n).toISOString());
+
+  const user = await resolveContextUser(opts.getUser, opts.storage);
+  const screen = safeCall(opts.getCurrentScreen, null);
+
+  return {
+    app: opts.app,
+    screen: typeof screen === "string" ? screen : null,
+    url: nullableString(safeCall(opts.getUrl, null)),
+    sessionId: opts.sessionId,
+    user,
+    source: opts.source ?? { screenId: null, sourceFile: null },
+    platform: opts.platform,
+    timezone: resolveTimezone(opts.getTimezone),
+    clientTimestamp: iso(now()),
+    native: buildNative(opts, typeof screen === "string" ? screen : null),
+    web: buildWeb(opts),
+    // 공급자가 없으면 null — 빈 배열을 상수로 보내지 않는다.
+    diagnostics: opts.getDiagnostics
+      ? normalizeDiagnostics(safeCall(opts.getDiagnostics, null))
+      : null,
+    extra: opts.extra ?? {},
+  };
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// 블록 조립
+// ────────────────────────────────────────────────────────────────────────────
+
+function hasNativeProvider(opts: BuildContextOpts): boolean {
+  return Boolean(
+    opts.getAppInfo ||
+      opts.getDevice ||
+      opts.getDisplay ||
+      opts.getNavPath ||
+      opts.getRouteParams ||
+      opts.screenSourceMap
+  );
+}
+
+function buildNative(
+  opts: BuildContextOpts,
+  screen: string | null
+): NativeContext | null {
+  if (opts.platform !== "native" || !hasNativeProvider(opts)) return null;
+
+  const navPathRaw = safeCall(opts.getNavPath, null);
+  const navPath = Array.isArray(navPathRaw)
+    ? navPathRaw.filter((s): s is string => typeof s === "string")
+    : // 스택을 못 구했으면 최소한 현재 화면 한 칸이라도 남긴다.
+      screen
+      ? [screen]
+      : [];
+
+  const app = safeCall(opts.getAppInfo, null) ?? {};
+  const device = safeCall(opts.getDevice, null) ?? {};
+  const display = safeCall(opts.getDisplay, null) ?? {};
+
+  return {
+    // 매핑이 없으면 여기만 null 이고 나머지 컨텍스트는 그대로 수집된다.
+    screenPath: lookupScreenPath(opts.screenSourceMap, screen),
+    navPath,
+    routeParams: toPlainRecord(safeCall(opts.getRouteParams, undefined)),
+    appInfo: {
+      version: nullableString(app.version),
+      channel: nullableString(app.channel),
+      updateId: nullableString(app.updateId),
+      runtimeVersion: nullableString(app.runtimeVersion),
+    },
+    device: {
+      model: nullableString(device.model),
+      osName: nullableString(device.osName),
+      osVersion: nullableString(device.osVersion),
+      deviceType: nullableString(device.deviceType),
+    },
+    display: {
+      width: nullableNumber(display.width),
+      height: nullableNumber(display.height),
+      pixelRatio: nullableNumber(display.pixelRatio),
+      fontScale: nullableNumber(display.fontScale),
+    },
+  };
+}
+
+function buildWeb(opts: BuildContextOpts): WebContext | null {
+  if (opts.platform !== "web" || !opts.getWebContext) return null;
+  const w = safeCall(opts.getWebContext, null) ?? {};
+  const vp = w.viewport ?? {};
+  return {
+    viewport: {
+      width: nullableNumber(vp.width),
+      height: nullableNumber(vp.height),
+      devicePixelRatio: nullableNumber(vp.devicePixelRatio),
+    },
+    userAgent: nullableString(w.userAgent),
+  };
+}
+
+function lookupScreenPath(
+  map: Record<string, string> | null | undefined,
+  screen: string | null
+): string | null {
+  if (!map || !screen) return null;
+  const hit = map[screen];
+  return typeof hit === "string" && hit.length > 0 ? hit : null;
+}
+
+/**
+ * 공급자가 준 스냅샷을 그대로 통과시킨다(배열만 확인).
+ * 여기서 배열을 새로 만들어 채우지 않는다 — 이 값은 수집기가 모은 결과여야 한다.
+ */
+function normalizeDiagnostics(
+  snap: DiagnosticsPayload | null
+): DiagnosticsPayload | null {
+  if (!snap || !Array.isArray(snap.network) || !Array.isArray(snap.logs)) {
+    return null;
+  }
+  return snap;
+}
+
+// ────────────────────────────────────────────────────────────────────────────
+// 헬퍼
+// ────────────────────────────────────────────────────────────────────────────
+
+/** 공급자를 호출하되, 없거나 던지면 fallback 을 쓴다. 한 항목의 실패가 제보를 막지 않는다. */
+function safeCall<T>(fn: (() => T) | undefined, fallback: T): T {
+  if (typeof fn !== "function") return fallback;
+  try {
+    return fn();
+  } catch {
+    return fallback;
+  }
+}
+
+function nullableString(v: unknown): string | null {
+  return typeof v === "string" && v.length > 0 ? v : null;
+}
+
+function nullableNumber(v: unknown): number | null {
+  return typeof v === "number" && Number.isFinite(v) ? v : null;
+}
+
+function resolveTimezone(getTimezone?: () => string | null): string | null {
+  const injected = safeCall(getTimezone, null);
+  if (typeof injected === "string" && injected.length > 0) return injected;
+  try {
+    // Intl 은 ES 표준이라 웹/RN(Hermes intl 빌드) 모두에서 쓸 수 있다.
+    const tz = new Intl.DateTimeFormat().resolvedOptions().timeZone;
+    return typeof tz === "string" && tz.length > 0 ? tz : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 라우트 파라미터를 JSON 왕복으로 정제한다.
+ * 함수는 버리고, 순환참조는 `[Circular]` 로 바꾼다 — 그대로 두면 제보 직렬화가 통째로
+ * 실패한다. (같은 객체가 형제로 두 번 나오면 두 번째도 [Circular] 로 보이는데,
+ * 안전한 쪽으로 과하게 판단하는 것이라 그대로 둔다.)
+ */
+function toPlainRecord(value: unknown): Record<string, unknown> | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const seen = new WeakSet<object>();
+  let json: string | undefined;
+  try {
+    json = JSON.stringify(value, (_key: string, v: unknown) => {
+      if (typeof v === "function") return undefined;
+      if (v && typeof v === "object") {
+        if (seen.has(v as object)) return "[Circular]";
+        seen.add(v as object);
+      }
+      return v;
+    });
+  } catch {
+    return null;
+  }
+  if (typeof json !== "string") return null;
+  try {
+    const parsed: unknown = JSON.parse(json);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : null;
+  } catch {
+    return null;
+  }
+}