@solhun/feedback-kit-core 0.1.0

package/src/index.ts

@@ -0,0 +1,179 @@
+// @solhun/feedback-kit-core 공개 진입점.
+//
+// 코어는 플랫폼에 의존하지 않는다(DOM·React Native API를 참조하지 않는다).
+// 웹/앱 패키지가 이 위에 각자의 UI를 얹고, 어댑터가 전송 대상을 결정한다.
+
+export type {
+  AppInfo,
+  ContextUser,
+  DeviceInfo,
+  DiagLogEntry,
+  DiagNetworkEntry,
+  DiagRequestRef,
+  DiagnosticsExcludeMatcher,
+  DiagnosticsPayload,
+  DisplayInfo,
+  ElementInfo,
+  FeedbackAdapter,
+  FeedbackContext,
+  FeedbackKind,
+  FeedbackPin,
+  FeedbackPriority,
+  FeedbackReport,
+  FeedbackScreenshot,
+  FeedbackStorage,
+  FeedbackUser,
+  GetCurrentScreenFn,
+  GetUserFn,
+  NativeContext,
+  SourceMapping,
+  SubmitResult,
+  WebContext,
+} from "./types.js";
+
+export type {
+  BuildContextOpts,
+  ContextProviders,
+  WebContextInput,
+} from "./context.js";
+export { buildContext, normalizeUser, resolveContextUser } from "./context.js";
+
+export type { BuildReportOpts, ReportParts } from "./report.js";
+export { buildReport } from "./report.js";
+
+export type {
+  FeedbackQueueOpts,
+  QueueStatus,
+  QueueStatusListener,
+  SubmitOutcome,
+} from "./queue.js";
+export {
+  BACKOFF_BASE_MS,
+  BACKOFF_MAX_MS,
+  defaultBackoff,
+  FeedbackQueue,
+  MAX_QUEUE_AGE_MS,
+  MAX_QUEUE_ITEMS,
+  RATE_LIMIT_MIN_DELAY_MS,
+} from "./queue.js";
+
+export {
+  byteLengthOf,
+  canUseKeepalive,
+  KEEPALIVE_BODY_LIMIT_BYTES,
+} from "./keepalive.js";
+
+export type { DiagnosticsInstallOpts } from "./diagnostics.js";
+export {
+  DiagnosticsCollector,
+  LOG_BUFFER_LIMIT,
+  MAX_LOG_MESSAGE_CHARS,
+  NETWORK_BUFFER_LIMIT,
+  REDACTED,
+  sanitizeUrl,
+  sharedDiagnostics,
+} from "./diagnostics.js";
+export { RingBuffer } from "./ring-buffer.js";
+
+export type {
+  AdapterName,
+  ConfigWarning,
+  ConfigWarningCode,
+  DiagnosticsSource,
+  FeedbackConfig,
+  ResolvedConfig,
+  Visibility,
+  VisibilityEnv,
+  VisibilityFn,
+  WidgetCorner,
+  WidgetPosition,
+} from "./config.js";
+export {
+  DEFAULT_ADAPTER,
+  DEFAULT_INTERNAL_ROLES,
+  DEFAULT_POSITION,
+  detectDevBuild,
+  diagnosticsProviderFor,
+  ENDPOINT_FROM_ADAPTER,
+  isInternalUser,
+  resolveConfig,
+  shouldShowWidget,
+} from "./config.js";
+
+export type { SourceLocation } from "./source-attr.js";
+export { parseSourceAttr, SOURCE_ATTR, sourceFromElement } from "./source-attr.js";
+
+// 위젯 헤드리스 계층. 화면 지도·리포트 모달·핀 지정·스크린샷 정책·포커스 순서.
+export type {
+  CaptureWithinLimitOpts,
+  ModalQueueLike,
+  ModalSubmitStatus,
+  PixelPoint,
+  PixelSize,
+  ReportModalListener,
+  ReportModalOpts,
+  ReportModalState,
+  ScreenshotCapture,
+  ScreenshotOutcome,
+  ScreenshotReencode,
+  ScreenshotStatus,
+  WidgetControllerOpts,
+  WidgetListener,
+  WidgetPlatform,
+  WidgetScreen,
+  WidgetState,
+} from "./widget/index.js";
+export {
+  captureWithinLimit,
+  COMMENT_MAX_CHARS,
+  COMMENT_REQUIRED_MESSAGE,
+  COMMENT_TOO_LONG_MESSAGE,
+  denormalizePin,
+  FLOATING_BUTTON_ID,
+  FocusRing,
+  MODAL_ACTION_ATTACH,
+  MODAL_ACTION_CANCEL,
+  MODAL_ACTION_PICK,
+  MODAL_ACTION_PIN,
+  MODAL_ACTION_REMOVE_SCREENSHOT,
+  MODAL_ACTION_RETRY,
+  MODAL_ACTION_SEND,
+  MODAL_FIELD_COMMENT,
+  MODAL_FIELD_PRIORITY,
+  normalizePin,
+  PinController,
+  ReportModalController,
+  SCREENSHOT_FAILED_MESSAGE,
+  SCREENSHOT_MAX_BASE64_BYTES,
+  SCREENSHOT_QUALITY_STEPS,
+  screenshotBytes,
+  SUBMIT_DONE_MESSAGE,
+  SUBMIT_FAILED_MESSAGE,
+  SUBMIT_PENDING_MESSAGE,
+  WidgetController,
+} from "./widget/index.js";
+
+// 어댑터. 코어의 다른 모듈은 이 아래를 import 하지 않는다 — 의존 방향은
+// "어댑터 → 코어" 한쪽뿐이고, 되짚어 참조하는 순간 어댑터 교체가 거짓이 된다.
+export type {
+  LassoAdapterOpts,
+  LassoEnvelope,
+  LassoFetch,
+  LassoRequestInit,
+  LassoResponseLike,
+  LinearIssueInput,
+  NotionPageInput,
+} from "./adapters/index.js";
+export {
+  buildLassoEnvelope,
+  buildLinearIssue,
+  buildNotionPage,
+  buildTitle,
+  createLassoAdapter,
+  LASSO_DEFAULT_ENDPOINT,
+  renderReportBody,
+  TITLE_MAX_CHARS,
+} from "./adapters/index.js";
+
+export { getOrCreateGuestId, guestUser } from "./guest-id.js";
+export { uuidv4 } from "./uuid.js";

package/src/keepalive.test.ts

@@ -0,0 +1,72 @@
+// keepalive 판단 유닛 테스트 (DP-252 TC6 — 이탈 대비의 경계 조건).
+//
+// 이 모듈이 틀리면 증상이 "가끔 전송이 통째로 실패"로 나타난다.
+// keepalive 한도를 넘긴 fetch 는 요청조차 나가지 않고 TypeError 로 죽기 때문에,
+// 경계값(64 KiB 정확히 / +1 바이트)을 테스트로 못 박아 둔다.
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import { byteLengthOf, canUseKeepalive, KEEPALIVE_BODY_LIMIT_BYTES } from "./keepalive.js";
+
+describe("canUseKeepalive", () => {
+  it("한도(64 KiB) 이하면 keepalive 를 쓴다", () => {
+    expect(KEEPALIVE_BODY_LIMIT_BYTES).toBe(65_536);
+    expect(canUseKeepalive(0)).toBe(true);
+    expect(canUseKeepalive(1_024)).toBe(true);
+    // 경계값 자체는 허용(표준의 quota 는 "초과 시 실패")
+    expect(canUseKeepalive(KEEPALIVE_BODY_LIMIT_BYTES)).toBe(true);
+  });
+
+  it("한도를 1바이트라도 넘기면 keepalive 를 끈다", () => {
+    expect(canUseKeepalive(KEEPALIVE_BODY_LIMIT_BYTES + 1)).toBe(false);
+    // 스크린샷이 붙은 제보의 현실적인 크기대
+    expect(canUseKeepalive(2 * 1024 * 1024)).toBe(false);
+  });
+
+  it("측정에 실패한 값(NaN·Infinity·음수)은 안전한 쪽(false)으로 떨어진다", () => {
+    expect(canUseKeepalive(Number.NaN)).toBe(false);
+    expect(canUseKeepalive(Number.POSITIVE_INFINITY)).toBe(false);
+    expect(canUseKeepalive(-1)).toBe(false);
+  });
+});
+
+describe("byteLengthOf", () => {
+  it("ASCII 는 길이와 바이트 수가 같다", () => {
+    expect(byteLengthOf("")).toBe(0);
+    expect(byteLengthOf("abc")).toBe(3);
+  });
+
+  it("한글·이모지는 코드 유닛이 아니라 UTF-8 바이트로 센다", () => {
+    // "한" = 3바이트, "가나다" = 9바이트
+    expect(byteLengthOf("가나다")).toBe(9);
+    // 이모지는 서로게이트 쌍(코드 유닛 2개)이지만 UTF-8 로는 4바이트
+    expect("🙂".length).toBe(2);
+    expect(byteLengthOf("🙂")).toBe(4);
+  });
+
+  it("한도 판정에 그대로 물린다 — 한글 본문이 길이로는 통과해도 바이트로는 막힌다", () => {
+    // 코드 유닛 30,000개(<65,536)지만 UTF-8 로는 90,000바이트(>65,536)
+    const body = "가".repeat(30_000);
+    expect(body.length).toBeLessThan(KEEPALIVE_BODY_LIMIT_BYTES);
+    expect(byteLengthOf(body)).toBe(90_000);
+    expect(canUseKeepalive(byteLengthOf(body))).toBe(false);
+  });
+
+  describe("TextEncoder 가 없는 런타임(구형 RN 등)", () => {
+    const original = (globalThis as { TextEncoder?: unknown }).TextEncoder;
+
+    afterEach(() => {
+      (globalThis as { TextEncoder?: unknown }).TextEncoder = original;
+    });
+
+    it("폴백은 실제 바이트 수보다 작지 않다 — 한도를 넘겨 켜는 일이 없다", () => {
+      delete (globalThis as { TextEncoder?: unknown }).TextEncoder;
+
+      for (const body of ["abc", "가나다", "🙂", "mixed 한글 🙂 text"]) {
+        const encoded = new (original as new () => { encode(s: string): { length: number } })()
+          .encode(body).length;
+        expect(byteLengthOf(body)).toBeGreaterThanOrEqual(encoded);
+      }
+    });
+  });
+});

package/src/keepalive.ts

@@ -0,0 +1,37 @@
+// 이탈(탭 닫기 / 화면 전환) 중에도 전송을 마치기 위한 keepalive 판단.
+//
+// 왜 별도 모듈인가:
+// `fetch(..., { keepalive: true })` 는 브라우저가 **요청 본문 64 KiB** 로 제한한다.
+// 한도를 넘기면 요청 자체가 TypeError 로 즉시 실패한다 — 즉 "일단 keepalive 를 켜두면
+// 안전하다"가 성립하지 않는다. 스크린샷이 붙은 제보는 수 MiB 라서 대부분 한도를 넘는다.
+//
+// 그래서 전송 계층은 본문 크기를 재고 이 함수로 갈라야 한다.
+// - 한도 이하(대부분의 텍스트 제보): keepalive 로 보내 이탈해도 전송이 끝난다.
+// - 한도 초과(스크린샷 동반): keepalive 없이 보낸다. 이탈로 중단되더라도 제보는 큐에
+//   남아 있으므로(2xx + ok=true 전에는 제거하지 않는다) 다음 마운트에서 자동 재전송된다.
+//   유실이 아니라 지연으로 떨어지는 것이 이 설계의 의도다.
+
+/** `fetch` keepalive 요청 본문 한도(바이트). Fetch 표준의 inflight keepalive quota. */
+export const KEEPALIVE_BODY_LIMIT_BYTES = 64 * 1024;
+
+/**
+ * 이 본문을 keepalive 로 보내도 되는지.
+ * @param bodyByteLength 직렬화된 요청 본문의 바이트 수.
+ */
+export function canUseKeepalive(bodyByteLength: number): boolean {
+  if (!Number.isFinite(bodyByteLength) || bodyByteLength < 0) return false;
+  return bodyByteLength <= KEEPALIVE_BODY_LIMIT_BYTES;
+}
+
+/**
+ * 문자열 본문의 UTF-8 바이트 수. `TextEncoder` 가 없으면(구형 RN 등) 보수적으로
+ * 근사한다 — 근사는 항상 실제보다 크거나 같게 잡아 한도를 넘겨 켜는 일이 없게 한다.
+ */
+export function byteLengthOf(body: string): number {
+  const g = globalThis as { TextEncoder?: new () => { encode(s: string): { length: number } } };
+  if (typeof g.TextEncoder === "function") {
+    return new g.TextEncoder().encode(body).length;
+  }
+  // 폴백: 코드 유닛당 최대 3바이트(서로게이트 쌍은 2유닛 → 4바이트라 여전히 상한).
+  return body.length * 3;
+}