@ait-co/devtools 0.1.19 → 0.1.20

package/README.md

@@ -1,5 +1,9 @@
 # @ait-co/devtools
 
+**한국어** · [English](./README.en.md)
+
+[![npm](https://img.shields.io/npm/v/@ait-co/devtools)](https://www.npmjs.com/package/@ait-co/devtools) [![license](https://img.shields.io/badge/license-BSD--3--Clause-blue)](./LICENSE)
+
 ![@ait-co/devtools — SDK mock + DevTools panel for Apps In Toss mini-apps](./assets/og/image.png)
 
 `@apps-in-toss/web-framework` SDK의 mock 라이브러리입니다. `@apps-in-toss/web-bridge`, `@apps-in-toss/web-analytics` import도 함께 mock됩니다.
@@ -14,10 +18,6 @@
 
 라이브 데모: <https://devtools.aitc.dev/> (이 repo의 `e2e/fixture/`를 GitHub Pages에 그대로 배포한 self-contained 데모).
 
-## Reference consumer
-
-[`sdk-example`](https://github.com/apps-in-toss-community/sdk-example)이 devtools의 reference consumer다. 모든 SDK API를 인터랙티브하게 실행해볼 수 있는 카탈로그 앱으로, 웹 데모는 <https://sdk-example.aitc.dev/>에서 바로 확인할 수 있다. 새 mock을 추가하면 sdk-example의 카드에서 그대로 동작하는 게 1차 sanity check. 단, 이 repo의 E2E suite는 sdk-example을 clone하지 않고 **내부 자기완결 fixture(`e2e/fixture/`)** 로 운영한다 — sdk-example이 깨져도 devtools CI는 영향받지 않는다.
-
 ## 설치
 
 ```bash
@@ -34,6 +34,10 @@ pnpm add -D @ait-co/devtools
 > 안 되는" 상황을 방지하기 위한 의도적 동작입니다. 누락된 API는
 > [이슈](https://github.com/apps-in-toss-community/devtools/issues)로 알려주세요.
 
+## Reference consumer
+
+[`sdk-example`](https://github.com/apps-in-toss-community/sdk-example)이 devtools의 reference consumer다. 모든 SDK API를 인터랙티브하게 실행해볼 수 있는 카탈로그 앱으로, 웹 데모는 <https://sdk-example.aitc.dev/>에서 바로 확인할 수 있다. 새 mock을 추가하면 sdk-example의 카드에서 그대로 동작하는 게 1차 sanity check. 단, 이 repo의 E2E suite는 sdk-example을 clone하지 않고 **내부 자기완결 fixture(`e2e/fixture/`)** 로 운영한다 — sdk-example이 깨져도 devtools CI는 영향받지 않는다.
+
 ## 번들러 설정
 
 ### Vite
@@ -215,15 +219,66 @@ if (process.env.NODE_ENV !== 'production') {
 
 데스크톱 크롬에서 잘 돌던 미니앱을 **실제 폰**에서 보고 싶을 때. Vite dev 서버를 Cloudflare quick tunnel(`*.trycloudflare.com`, **계정 불필요**)로 노출하고, 폰에는 고정 URL의 launcher PWA를 한 번만 추가해 그 안에서 매번의 tunnel URL을 띄웁니다.
 
-1. unplugin에 `tunnel: true` 추가:
-   ```ts
-   // vite.config.ts
-   plugins: [aitDevtools.vite({ tunnel: true })]
-   ```
-2. `pnpm dev` (= `vite`) 실행. dev 서버가 listen하면 터미널에 공개 URL + ASCII QR이 출력됩니다. (첫 실행 시 `cloudflared` 바이너리를 자동 다운로드합니다.)
-3. 폰에서 `https://devtools.aitc.dev/launcher/`를 열고 **홈 화면에 추가** (iOS Safari "공유 → 홈 화면에 추가", Android Chrome "앱 설치"). 이걸 한 번만 하면 됩니다 — launcher 자체는 URL이 바뀌지 않습니다.
-4. launcher 아이콘으로 실행 → 카메라로 2번의 QR을 스캔(또는 URL을 붙여넣기) → dev 앱이 주소창 없는 풀스크린으로 뜹니다.
-5. 다음 세션엔 `pnpm dev` → 새 URL 스캔만 하면 됩니다. launcher는 마지막 URL을 기억하고, "Rescan" 버튼으로 언제든 교체할 수 있습니다.
+셋업은 세 갈래입니다:
+
+- **프로젝트당 1회** — `vite.config`에 옵션 + `package.json`에 pnpm 설정 + (선택) `dev:phone` 스크립트
+- **폰당 1회** — launcher PWA를 홈 화면에 추가
+- **매 세션** — `pnpm dev:phone` (또는 `AIT_TUNNEL=1 pnpm dev`) 한 줄
+
+### 1. 프로젝트당 1회 셋업
+
+(a) **`vite.config.ts`에 `tunnel` 옵션 추가** — 항상 켜져 있어 매번 cloudflared가 떠도 괜찮으면 `tunnel: true`, 평소엔 끄고 명시할 때만 켜고 싶으면 env-gate 권장:
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import aitDevtools from '@ait-co/devtools/unplugin';
+
+export default defineConfig({
+  plugins: [
+    aitDevtools.vite({
+      tunnel: !!process.env.AIT_TUNNEL, // 평소 OFF, AIT_TUNNEL=1 일 때만 ON
+    }),
+  ],
+});
+```
+
+> `process.env.AIT_TUNNEL`은 `vite.config.ts`를 로드하는 시점(= vite 프로세스 기동 시)에 평가됩니다. 따라서 env 변수는 **vite를 띄우기 전에** 설정되어 있어야 합니다 (아래 (c)의 `dev:phone` 스크립트가 이를 자동으로 해결합니다).
+
+(b) **`package.json`에 pnpm 10+ 빌드 스크립트 허용** — pnpm은 보안상 dependency의 postinstall을 기본 차단합니다. `cloudflared`는 postinstall에서 바이너리(~38 MB)를 받으므로 명시 허용 필요:
+
+```json
+{
+  "pnpm": {
+    "onlyBuiltDependencies": ["cloudflared"]
+  }
+}
+```
+
+> 명시하지 않아도 동작은 됩니다 — `tunnel.ts`가 첫 기동 시 `cloudflared.install()`을 lazy로 호출. 다만 `pnpm install`마다 "Ignored build scripts" 경고가 남고, 바이너리 다운로드가 첫 `pnpm dev` 시점으로 미뤄집니다. 참고: [`sdk-example#60`](https://github.com/apps-in-toss-community/sdk-example/pull/60).
+
+(c) **(선택) `dev:phone` 스크립트** — env 변수 매번 타기 귀찮으면:
+
+```json
+{
+  "scripts": {
+    "dev": "vite",
+    "dev:phone": "AIT_TUNNEL=1 vite"
+  }
+}
+```
+
+### 2. 폰당 1회 셋업
+
+폰에서 `https://devtools.aitc.dev/launcher/`를 열고 **홈 화면에 추가**합니다 (iOS Safari "공유 → 홈 화면에 추가", Android Chrome "앱 설치"). launcher 자체는 URL이 바뀌지 않으니 한 번만 하면 됩니다.
+
+### 3. 매 세션
+
+1. 데스크톱에서 `pnpm dev:phone`을 실행합니다 (1-(c) 스크립트를 추가하지 않았다면 `AIT_TUNNEL=1 pnpm dev`). 터미널에 `https://*.trycloudflare.com` URL + ASCII QR이 출력됩니다.
+2. 폰의 launcher 아이콘 실행 → 카메라로 QR 스캔(또는 URL 붙여넣기) → 주소창 없는 풀스크린으로 dev 앱이 뜹니다.
+3. 다음 세션엔 새 URL을 스캔만 하면 됩니다. launcher는 마지막 URL을 기억하고, "Rescan" 버튼으로 언제든 교체할 수 있습니다.
+
+### 배경
 
 > **왜 launcher를 거치나요?** quick tunnel URL은 매 실행마다 바뀌므로 그 URL 자체를 PWA로 설치하면 다음 세션엔 죽은 링크가 됩니다. cross-origin으로 페이지를 전환하면 iOS/Android 모두 standalone(크롬리스)이 깨집니다. → 고정 URL의 launcher를 한 번 설치하고, 그 안의 `<iframe>`으로 그날의 dev 앱을 full-bleed로 보여주는 구조입니다.
 >
@@ -231,6 +286,10 @@ if (process.env.NODE_ENV !== 'production') {
 >
 > `tunnel` 옵션은 Vite dev 모드에서만 동작합니다 — production 빌드는 `forceEnable`이어도 터널을 띄우지 않습니다. 다른 번들러(Webpack/Rspack 등)에서는 무시됩니다. 이 옵션을 켜면 `cloudflared` / `qrcode-terminal`가 동적 import로만 로드되므로, 끄면 번들 그래프에 들어오지 않습니다.
 
+### 한 줄 셋업 (예정)
+
+위 "프로젝트당 1회" 단계(vite.config 패치 + `onlyBuiltDependencies` + `dev:phone` 스크립트)는 향후 [`agent-plugin`](https://github.com/apps-in-toss-community/agent-plugin)이 `/ait setup phone` 같은 단일 명령으로 흡수할 예정입니다 (명령 이름은 잠정). 이 README가 그 자동화의 명세서 역할을 하므로, 수동 셋업 단계가 줄어들어도 동작 모델 자체는 동일합니다.
+
 ## Device API 모드 시스템
 
 디바이스 관련 API(카메라, 위치, 클립보드 등)는 세 가지 모드로 동작합니다:
@@ -384,7 +443,7 @@ Landscape로 전환하면:
 **Show Apps in Toss nav bar** 토글(기본 on)을 켜면:
 - 토스 호스트의 상단 nav bar(뒤로가기 / 앱 아이콘·이름 / ⋯ / ×)를 48px 높이로 오버레이
 - status bar 바로 아래, safe area top 이후에 배치
-- **중요**: 이 48px는 `env(safe-area-inset-top)` 및 `SafeAreaInsets.get().top`에 **포함되지 않습니다** (공식 SDK 동작). 토스 공식 예제들도 `insets.top + 48` 패턴으로 보정합니다.
+- **중요**: 이 48px는 `env(safe-area-inset-top)` 및 `SafeAreaInsets.get().top`에 **포함되지 않습니다** (SDK 동작). 토스 측 예제들도 `insets.top + 48` 패턴으로 보정합니다.
 
 ### 콘솔에서 직접 조작
 
@@ -768,6 +827,37 @@ import '@ait-co/devtools/panel';
 | `@ait-co/devtools/panel` | Floating DevTools Panel (import 시 자동 마운트) |
 | `@ait-co/devtools/unplugin` | 번들러 플러그인 (.vite, .webpack, .rspack, .esbuild, .rollup) |
 
+## 텔레메트리
+
+devtools는 두 단계의 텔레메트리를 사용합니다.
+
+### Tier 0 — 익명 사용 신호 (기본 ON, opt-out)
+
+패널이 열릴 때 하루 1회 익명 ping을 전송합니다.
+
+수집 항목: `source`, `version`, `ts` — PII 없음, `anon_id` 없음. 서버가 IP+UA 기반 daily hash를 생성하지만 저장하지 않습니다.
+
+끄는 방법:
+- 패널 Environment 탭 → "익명 사용 신호 (Tier 0)" 토글 OFF
+- `localStorage.setItem('__ait_telemetry:t0_off', '1')` (콘솔에서 직접)
+- 환경 변수: `AITC_TELEMETRY=off`
+
+### Tier 1 — 확장 텔레메트리 (기본 OFF, opt-in)
+
+패널 최초 실행 시 동의 토스트로 묻습니다. 동의한 경우에만 수집됩니다.
+
+수집 항목: `panel_open`, `tab_view`, `session_duration` 이벤트 + 익명 UUID(`anon_id`).
+
+끄는 방법:
+- 패널 Environment 탭 → "확장 텔레메트리 (Tier 1)" 토글 OFF
+- 수집된 데이터 삭제: 패널 Environment 탭 → "내 데이터 삭제"
+
+개인정보 처리방침: <https://docs.aitc.dev/privacy>
+
 ## 라이센스
 
 BSD 3-Clause
+
+---
+
+커뮤니티 오픈소스 프로젝트입니다.

package/dist/panel/index.js

@@ -36,7 +36,13 @@ const en = {
 	"env.row.safeArea.top": "Top",
 	"env.row.safeArea.bottom": "Bottom",
 	"env.telemetry.section": "Telemetry",
-	"env.telemetry.row": "Telemetry",
+	"env.telemetry.t0Row": "Anonymous usage signal (Tier 0)",
+	"env.telemetry.t0On": "On",
+	"env.telemetry.t0Off": "Off",
+	"env.telemetry.t0TurnOn": "Turn on",
+	"env.telemetry.t0TurnOff": "Turn off",
+	"env.telemetry.t0Desc": "Version + date only, no PII. Once per day. Helps improve the package.",
+	"env.telemetry.row": "Extended telemetry (Tier 1)",
 	"env.telemetry.on": "On",
 	"env.telemetry.off": "Off",
 	"env.telemetry.turnOn": "Turn on",
@@ -49,7 +55,7 @@ const en = {
 	"env.telemetry.deleted": "Deleted",
 	"env.telemetry.deleteFailedRetry": "Delete failed (please retry)",
 	"env.telemetry.deleteFailed": "Delete failed",
-	"env.telemetry.privacyLink": "Privacy policy",
+	"env.telemetry.privacyLink": "Privacy policy →",
 	"env.section.language": "Language",
 	"env.language.row": "Language",
 	"env.language.ko": "한국어",
@@ -181,7 +187,13 @@ const ko = {
 	"env.row.safeArea.top": "Top",
 	"env.row.safeArea.bottom": "Bottom",
 	"env.telemetry.section": "Telemetry",
-	"env.telemetry.row": "Telemetry",
+	"env.telemetry.t0Row": "익명 사용 신호 (Tier 0)",
+	"env.telemetry.t0On": "On",
+	"env.telemetry.t0Off": "Off",
+	"env.telemetry.t0TurnOn": "Turn on",
+	"env.telemetry.t0TurnOff": "Turn off",
+	"env.telemetry.t0Desc": "버전·날짜만 수집, PII 없음. 하루 1회. 패키지 개선에 사용됩니다.",
+	"env.telemetry.row": "확장 텔레메트리 (Tier 1)",
 	"env.telemetry.on": "On",
 	"env.telemetry.off": "Off",
 	"env.telemetry.turnOn": "Turn on",
@@ -194,7 +206,7 @@ const ko = {
 	"env.telemetry.deleted": "삭제 완료",
 	"env.telemetry.deleteFailedRetry": "삭제 실패 (다시 시도해주세요)",
 	"env.telemetry.deleteFailed": "삭제 실패",
-	"env.telemetry.privacyLink": "개인정보 처리방침",
+	"env.telemetry.privacyLink": "개인정보 처리방침 →",
 	"env.section.language": "Language",
 	"env.language.row": "Language",
 	"env.language.ko": "한국어",
@@ -720,11 +732,56 @@ const KEY_CONSENT = "__ait_telemetry:consent";
 const KEY_REPROMPT_AFTER = "__ait_telemetry:reprompt_after";
 const KEY_POLICY_VERSION = "__ait_telemetry:policy_version";
 const KEY_ANON_ID = "__ait_telemetry:anon_id";
+const KEY_T0_LAST_SENT = "__ait_telemetry:t0_last_sent";
+const KEY_T0_OFF = "__ait_telemetry:t0_off";
+/**
+* Returns true if Tier 0 ping is enabled.
+* Disabled when `localStorage.__ait_telemetry:t0_off = '1'`
+* or `process.env.AITC_TELEMETRY === 'off'`.
+*/
+function isTier0Enabled() {
+	if (typeof process !== "undefined" && process.env.AITC_TELEMETRY === "off") return false;
+	try {
+		return localStorage.getItem(KEY_T0_OFF) !== "1";
+	} catch {
+		return true;
+	}
+}
+/**
+* Sets or clears the Tier 0 opt-out marker.
+*/
+function setTier0Enabled(enabled) {
+	try {
+		if (enabled) localStorage.removeItem(KEY_T0_OFF);
+		else localStorage.setItem(KEY_T0_OFF, "1");
+	} catch {}
+}
+/**
+* Returns true if Tier 0 has already been sent today (YYYY-MM-DD).
+*/
+function hasSentTier0Today() {
+	try {
+		const stored = localStorage.getItem(KEY_T0_LAST_SENT);
+		if (!stored) return false;
+		return stored === (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+	} catch {
+		return false;
+	}
+}
+/**
+* Records that Tier 0 was sent today.
+*/
+function markTier0Sent() {
+	try {
+		const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+		localStorage.setItem(KEY_T0_LAST_SENT, today);
+	} catch {}
+}
 /**
 * Current policy version. Bump this string whenever the privacy policy changes.
 * Users who previously granted on an older version will be re-prompted once.
 */
-const CURRENT_POLICY_VERSION = "2026-05-12";
+const CURRENT_POLICY_VERSION = "2026-05-18";
 /** 30 days in milliseconds */
 const THIRTY_DAYS_MS = 720 * 60 * 60 * 1e3;
 function readConsentState() {
@@ -763,7 +820,7 @@ function getOrCreateAnonId() {
 function resolveEffectiveConsent() {
 	const raw = localStorage.getItem(KEY_CONSENT);
 	if (raw === "granted") {
-		if (readPolicyVersion() !== "2026-05-12") {
+		if (readPolicyVersion() !== "2026-05-18") {
 			localStorage.removeItem(KEY_CONSENT);
 			localStorage.removeItem(KEY_POLICY_VERSION);
 			return "undecided";
@@ -889,6 +946,7 @@ function delay(ms) {
 async function send(event, version, meta) {
 	if (readConsentState() !== "granted") return;
 	const payload = {
+		tier: 1,
 		source: "devtools",
 		event,
 		anon_id: getOrCreateAnonId(),
@@ -909,6 +967,7 @@ async function send(event, version, meta) {
 function sendBeaconEvent(event, version, meta) {
 	if (readConsentState() !== "granted") return;
 	const payload = {
+		tier: 1,
 		source: "devtools",
 		event,
 		anon_id: getOrCreateAnonId(),
@@ -929,6 +988,49 @@ function sendBeaconEvent(event, version, meta) {
 	}).catch(() => {});
 }
 //#endregion
+//#region src/telemetry/tier0.ts
+/**
+* Tier 0 telemetry — opt-out, fire-and-forget daily ping.
+*
+* Payload: { tier: 0, source: 'devtools', ts: number, version: string }
+* No anon_id. No event name. No meta.
+*
+* Rules:
+*   - Sent once per calendar day (localStorage daily marker).
+*   - Skipped when __ait_telemetry:t0_off = '1' or AITC_TELEMETRY=off.
+*   - 5 s timeout, no retry. Failure is silently dropped.
+*/
+/**
+* Sends the Tier 0 daily ping if eligible.
+* Returns true if a ping was sent, false if skipped or failed.
+*/
+async function sendTier0Ping(version) {
+	if (!isTier0Enabled()) return false;
+	if (hasSentTier0Today()) return false;
+	const payload = {
+		tier: 0,
+		source: "devtools",
+		ts: Date.now(),
+		version
+	};
+	const controller = new AbortController();
+	const timeoutId = setTimeout(() => controller.abort(), 5e3);
+	try {
+		await fetch(`${TELEMETRY_ENDPOINT}/e`, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify(payload),
+			signal: controller.signal
+		});
+		markTier0Sent();
+		return true;
+	} catch {
+		return false;
+	} finally {
+		clearTimeout(timeoutId);
+	}
+}
+//#endregion
 //#region src/telemetry/index.ts
 /**
 * Telemetry client — internal to @ait-co/devtools.
@@ -948,7 +1050,7 @@ function readGlobalString(key) {
 }
 const TELEMETRY_ENDPOINT = readGlobalString("__TELEMETRY_ENDPOINT__") ?? "https://t.aitc.dev";
 function getVersion() {
-	return "0.1.19";
+	return "0.1.20";
 }
 let panelVisibleSince = null;
 let accumulatedMs = 0;
@@ -972,11 +1074,12 @@ function wirePagehide() {
 }
 /**
 * Call once after panel mounts.
-* Handles: consent check, optional toast, panel_mount event, pagehide wiring.
+* Handles: Tier 0 ping, consent check, optional toast, panel_mount event, pagehide wiring.
 */
 function init() {
 	if (typeof window === "undefined" || typeof document === "undefined") return;
 	wirePagehide();
+	sendTier0Ping(getVersion());
 	if (resolveEffectiveConsent() === "granted") {
 		getOrCreateAnonId();
 		send("panel_mount", getVersion());
@@ -2450,6 +2553,18 @@ function buildLanguageSection() {
 	return h("div", { className: "ait-section" }, h("div", { className: "ait-section-title" }, t("env.section.language")), h("div", { className: "ait-row" }, h("label", {}, t("env.language.row")), select));
 }
 function buildTelemetrySection() {
+	const t0Enabled = isTier0Enabled();
+	const t0StatusLabel = h("span", { style: `font-size:12px;font-weight:600;color:${t0Enabled ? "#4ade80" : "#888"}` }, t0Enabled ? t("env.telemetry.t0On") : t("env.telemetry.t0Off"));
+	const t0ToggleBtn = h("button", {
+		className: "ait-btn ait-btn-sm",
+		style: "font-size:11px"
+	}, t0Enabled ? t("env.telemetry.t0TurnOff") : t("env.telemetry.t0TurnOn"));
+	t0ToggleBtn.addEventListener("click", () => {
+		setTier0Enabled(!t0Enabled);
+		window.dispatchEvent(new CustomEvent("__ait:panel-switch-tab", { detail: { tab: "env" } }));
+	});
+	const t0Row = h("div", { className: "ait-row" }, h("label", {}, t("env.telemetry.t0Row")), h("span", { style: "display:flex;align-items:center;gap:8px" }, t0StatusLabel, t0ToggleBtn));
+	const t0Desc = h("div", { style: "font-size:11px;color:#666;margin-bottom:6px" }, t("env.telemetry.t0Desc"));
 	const isGranted = readConsentState() === "granted";
 	const statusLabel = h("span", { style: `font-size:12px;font-weight:600;color:${isGranted ? "#4ade80" : "#888"}` }, isGranted ? t("env.telemetry.on") : t("env.telemetry.off"));
 	const toggleBtn = h("button", {
@@ -2492,7 +2607,7 @@ function buildTelemetrySection() {
 		style: "font-size:11px;color:#666;text-decoration:none"
 	});
 	privacyLink.textContent = t("env.telemetry.privacyLink");
-	return h("div", { className: "ait-section" }, h("div", { className: "ait-section-title" }, t("env.telemetry.section")), statusRow, h("div", { style: "margin-bottom:6px" }, anonIdEl), h("div", {
+	return h("div", { className: "ait-section" }, h("div", { className: "ait-section-title" }, t("env.telemetry.section")), t0Row, t0Desc, statusRow, h("div", { style: "margin-bottom:6px" }, anonIdEl), h("div", {
 		className: "ait-btn-row",
 		style: "align-items:center;gap:8px;margin-top:6px"
 	}, deleteBtn, deleteStatus), h("div", { style: "margin-top:8px" }, privacyLink));
@@ -4052,7 +4167,7 @@ function mount() {
 		mockBadge.textContent = aitState.state.panelEditable ? t("panel.editMode.on") : t("panel.editMode.off");
 		refreshPanel();
 	});
-	const headerRight = h("span", { style: "display:flex;align-items:center;gap:6px" }, mockBadge, h("span", { style: "font-size:11px;color:#666;font-weight:400" }, `v0.1.19`), closeBtn);
+	const headerRight = h("span", { style: "display:flex;align-items:center;gap:6px" }, mockBadge, h("span", { style: "font-size:11px;color:#666;font-weight:400" }, `v0.1.20`), closeBtn);
 	const header = h("div", { className: "ait-panel-header" }, h("span", {}, t("panel.title")), headerRight);
 	tabsEl = h("div", { className: "ait-panel-tabs" });
 	for (const tab of getTabs()) {