@sayren/storefront-sdk 0.1.0 → 0.2.1

package/dist/analytics/index.d.mts

@@ -0,0 +1,82 @@
+//#region src/analytics/index.d.ts
+/**
+ * 방문 분석 브라우저 모듈 — `@sayren/storefront-sdk/analytics`.
+ *
+ * 페이지뷰·상품 조회·목록 노출·검색·체류를 모아 배치로 보낸다. 장바구니·결제·구매는 스토어프론트 API가
+ * 서버에서 기록하므로 여기서 보내지 않는다(클라이언트에 `visitorId`·`sessionId`를 넘기면 이어진다).
+ *
+ * - 식별자는 셀러 도메인의 1st-party 쿠키(`sy_vid` 1년, `sy_sid` 30분 비활동)다. SSR 서버도 같은 쿠키를 읽는다.
+ * - 같은 행동은 한 번만 보낸다(StrictMode 이중 실행·리렌더 흡수). 서버도 결정적 id로 한 번 더 거른다.
+ * - 동의 전(`pending`)에는 쿠키를 만들지 않고 큐에만 쌓는다. `denied`면 버린다.
+ * - localhost·사설 IP에서는 기본으로 보내지 않는다(`debug: true`로 켠다).
+ */
+export type AnalyticsConsent = "granted" | "denied" | "pending";
+export interface AnalyticsOptions {
+  /** 스토어프론트 API 베이스 — 예: `https://api.sayren.app/storefront/v1` */
+  baseUrl: string;
+  /** 테넌트 스토어 코드 */
+  storeCode: string;
+  /** 동의 상태. 기본 `pending` — 셀러의 동의 배너가 `setConsent`로 바꾼다 */
+  consent?: AnalyticsConsent;
+  /** 페이지뷰를 자동으로 보낸다(첫 페이지 + History API 이동). 기본 true */
+  autoPageViews?: boolean;
+  /** 개발 호스트(localhost 등)에서도 보낸다. 기본 false */
+  debug?: boolean;
+  /** 쿠키 도메인 — 서브도메인끼리 방문자를 공유하려면 `.myshop.com` */
+  cookieDomain?: string;
+  /** 배치 전송 간격(ms). 기본 5000 */
+  flushIntervalMs?: number;
+}
+export type AnalyticsTrackInput = {
+  name: "product_view";
+  productId: string;
+  variantId?: string;
+} | {
+  name: "product_list_view";
+  listId: string;
+  productIds: string[];
+} | {
+  name: "search";
+  query: string;
+  resultCount: number;
+};
+export interface Analytics {
+  /** 행동 이벤트 — 같은 페이지뷰 안의 같은 행동은 한 번만 보낸다 */
+  track(input: AnalyticsTrackInput): void;
+  /** 페이지뷰를 직접 보낸다(`autoPageViews: false`일 때) */
+  page(): void;
+  setConsent(consent: AnalyticsConsent): void;
+  /** 방문자·세션 ID — `createStorefrontClient({ visitorId, sessionId })`에 넘긴다. 동의 전·거부면 null */
+  ids(): {
+    visitorId: string;
+    sessionId: string;
+  } | null;
+  /** 큐를 지금 보낸다 */
+  flush(): void;
+  /** 리스너·타이머를 걷는다 */
+  destroy(): void;
+}
+/** 브라우저 의존부 — 테스트는 가짜 환경을 넣는다 */
+export interface AnalyticsEnv {
+  now(): number;
+  href(): string;
+  referrer(): string;
+  hostname(): string;
+  getCookie(name: string): string | null;
+  setCookie(name: string, value: string, maxAgeSec: number, domain?: string): void;
+  /** 배치를 보낸다(sendBeacon, 안 되면 fetch keepalive) */
+  send(url: string, body: string): void;
+  randomId(): string;
+  visible(): boolean;
+  prerendering(): boolean;
+  webdriver(): boolean;
+  /** 이벤트 리스너를 달고 떼는 함수를 돌려준다 */
+  on(event: "visibilitychange" | "pagehide" | "prerenderingchange", fn: () => void): () => void;
+  /** History API 이동(pushState·replaceState·popstate)을 구독한다 */
+  onNavigate(fn: () => void): () => void;
+  setInterval(fn: () => void, ms: number): () => void;
+}
+export declare function createAnalytics(options: AnalyticsOptions): Analytics;
+/** 테스트·비표준 런타임용 — 환경을 직접 넣는다 */
+export declare function createAnalyticsWith(options: AnalyticsOptions, env: AnalyticsEnv): Analytics;
+//#endregion

package/dist/analytics/index.mjs

@@ -0,0 +1,315 @@
+import { i as ANALYTICS_SESSION_COOKIE, n as safeDecode, o as ANALYTICS_VISITOR_COOKIE } from "../analytics-ids-o0a07Ohr.mjs";
+//#region src/analytics/index.ts
+const VISITOR_MAX_AGE_SEC = 31536e3;
+const SESSION_MAX_AGE_SEC = 1800;
+/** 세션을 시작한 캠페인 — 다른 캠페인으로 들어오면 새 세션이다 */
+const SESSION_CAMPAIGN_COOKIE = "sy_scmp";
+const MAX_BATCH = 50;
+/** 이벤트 이름당 분당 상한 — 무한 루프 버그가 트래픽을 만들지 못하게 */
+const PER_NAME_PER_MINUTE = 30;
+/**
+* 전체 분당 상한 — 서버의 방문자당 분당 한도(120)보다 낮게 둬, SDK가 보낸 이벤트가 서버 한도에 걸려
+* 조용히 버려지지 않게 한다(이름당 상한만으로는 이름 5종 × 30 = 150까지 갈 수 있다).
+*/
+const TOTAL_PER_MINUTE = 100;
+const MAX_QUEUE = 500;
+const DEV_HOST = /^(localhost|127\.\d+\.\d+\.\d+|\[?::1\]?|0\.0\.0\.0|10\.\d+\.\d+\.\d+|192\.168\.\d+\.\d+|172\.(1[6-9]|2\d|3[01])\.\d+\.\d+)$|\.local$/i;
+function createAnalytics(options) {
+	if (typeof window === "undefined" || typeof document === "undefined") return noopAnalytics;
+	return createAnalyticsWith(options, browserEnv());
+}
+/** 테스트·비표준 런타임용 — 환경을 직접 넣는다 */
+function createAnalyticsWith(options, env) {
+	const endpoint = `${options.baseUrl.replace(/\/+$/, "")}/events`;
+	const enabled = options.debug === true || !DEV_HOST.test(env.hostname());
+	let consent = options.consent ?? "pending";
+	let queue = [];
+	let pageViewId = "";
+	let pageKey = "";
+	/** 지금 페이지뷰의 URL — SPA 이동 뒤 이전 페이지의 체류를 보낼 때 새 URL과 섞이지 않게 */
+	let pageHref = "";
+	let visibleSince = null;
+	let visibleMs = 0;
+	let engagementSent = false;
+	let firstPage = true;
+	/**
+	* 지금 페이지뷰를 보냈는가 — 상한으로 페이지뷰가 버려졌으면 그 페이지의 상품 조회·목록·검색·체류도 보내지 않는다.
+	* 그러지 않으면 존재하지 않는 페이지뷰를 가리키는 이벤트가 남는다.
+	*/
+	let pageAccepted = false;
+	const seen = /* @__PURE__ */ new Set();
+	let rateMinute = -1;
+	const perName = /* @__PURE__ */ new Map();
+	let totalThisMinute = 0;
+	const cleanups = [];
+	const campaignOf = (href) => {
+		try {
+			const params = new URL(href).searchParams;
+			const source = params.get("utm_source");
+			return source ? `${source}|${params.get("utm_campaign") ?? ""}` : null;
+		} catch {
+			return null;
+		}
+	};
+	/** 동의가 있을 때만 쿠키를 읽고 만든다. 세션은 이벤트마다 30분 연장한다 */
+	const ensureIds = () => {
+		if (consent !== "granted") return null;
+		let visitorId = env.getCookie(ANALYTICS_VISITOR_COOKIE);
+		if (!visitorId) visitorId = env.randomId();
+		let sessionId = env.getCookie(ANALYTICS_SESSION_COOKIE);
+		const campaign = campaignOf(env.href());
+		if (campaign && campaign !== env.getCookie(SESSION_CAMPAIGN_COOKIE)) {
+			sessionId = null;
+			env.setCookie(SESSION_CAMPAIGN_COOKIE, campaign, SESSION_MAX_AGE_SEC, options.cookieDomain);
+		}
+		if (!sessionId) sessionId = env.randomId();
+		env.setCookie(ANALYTICS_VISITOR_COOKIE, visitorId, VISITOR_MAX_AGE_SEC, options.cookieDomain);
+		env.setCookie(ANALYTICS_SESSION_COOKIE, sessionId, SESSION_MAX_AGE_SEC, options.cookieDomain);
+		return {
+			visitorId,
+			sessionId
+		};
+	};
+	const allowRate = (name) => {
+		const minute = Math.floor(env.now() / 6e4);
+		if (minute !== rateMinute) {
+			rateMinute = minute;
+			perName.clear();
+			totalThisMinute = 0;
+		}
+		const used = perName.get(name) ?? 0;
+		if (used >= PER_NAME_PER_MINUTE || totalThisMinute >= TOTAL_PER_MINUTE) return false;
+		perName.set(name, used + 1);
+		totalThisMinute += 1;
+		return true;
+	};
+	/** 큐에 넣었으면 true — 중복·상한·거부로 버리면 false */
+	const push = (event, dedupeKey) => {
+		if (!enabled || consent === "denied") return false;
+		if (seen.has(dedupeKey) || !allowRate(event.name)) return false;
+		seen.add(dedupeKey);
+		if (queue.length >= MAX_QUEUE) queue.shift();
+		queue.push(event);
+		if (queue.length >= MAX_BATCH) flush();
+		return true;
+	};
+	const flush = () => {
+		if (!enabled || queue.length === 0) return;
+		const ids = ensureIds();
+		if (!ids) return;
+		while (queue.length > 0) {
+			const events = queue.splice(0, MAX_BATCH);
+			const batch = {
+				storeCode: options.storeCode,
+				...ids,
+				events,
+				...env.webdriver() ? { context: { webdriver: true } } : {}
+			};
+			env.send(endpoint, JSON.stringify(batch));
+		}
+	};
+	const occurredAt = () => new Date(env.now()).toISOString();
+	/** 지금 페이지의 체류를 한 번 보낸다(이동·숨김·닫힘 중 먼저 오는 때) */
+	const endPage = () => {
+		if (!pageViewId || engagementSent || !pageAccepted) return;
+		if (visibleSince !== null) {
+			visibleMs += env.now() - visibleSince;
+			visibleSince = env.visible() ? env.now() : null;
+		}
+		engagementSent = true;
+		push({
+			name: "page_engagement",
+			occurredAt: occurredAt(),
+			url: pageHref,
+			pageViewId,
+			visibleMs: Math.max(0, Math.round(visibleMs))
+		}, `engagement:${pageViewId}`);
+	};
+	const startPage = () => {
+		const href = env.href();
+		let key = href;
+		try {
+			const url = new URL(href);
+			key = `${url.pathname}${url.search}`;
+		} catch {}
+		if (key === pageKey) return;
+		endPage();
+		pageKey = key;
+		pageHref = href;
+		pageViewId = env.randomId();
+		visibleMs = 0;
+		visibleSince = env.visible() ? env.now() : null;
+		engagementSent = false;
+		const referrer = firstPage ? env.referrer() : "";
+		pageAccepted = push({
+			name: "page_view",
+			occurredAt: occurredAt(),
+			url: href,
+			pageViewId,
+			...referrer ? { referrer } : {}
+		}, `page:${pageViewId}`);
+		if (pageAccepted) firstPage = false;
+	};
+	/** 프리렌더·숨은 탭은 화면에 보이는 순간 첫 페이지뷰를 보낸다 */
+	const startWhenVisible = () => {
+		if (!env.prerendering() && env.visible()) {
+			startPage();
+			return;
+		}
+		const tryStart = () => {
+			if (!pageViewId && !env.prerendering() && env.visible()) startPage();
+		};
+		cleanups.push(env.on("prerenderingchange", tryStart), env.on("visibilitychange", tryStart));
+	};
+	cleanups.push(env.on("visibilitychange", () => {
+		if (env.visible()) {
+			if (pageViewId && visibleSince === null) visibleSince = env.now();
+			return;
+		}
+		endPage();
+		flush();
+	}), env.on("pagehide", () => {
+		endPage();
+		flush();
+	}), env.setInterval(flush, options.flushIntervalMs ?? 5e3));
+	if (options.autoPageViews !== false) {
+		startWhenVisible();
+		cleanups.push(env.onNavigate(startPage));
+	}
+	return {
+		track(input) {
+			if (!pageViewId) startPage();
+			if (!pageAccepted) return;
+			const common = {
+				occurredAt: occurredAt(),
+				url: env.href(),
+				pageViewId
+			};
+			switch (input.name) {
+				case "product_view":
+					push({
+						...common,
+						name: "product_view",
+						productId: input.productId,
+						...input.variantId ? { variantId: input.variantId } : {}
+					}, `product:${pageViewId}:${input.productId}`);
+					return;
+				case "product_list_view":
+					push({
+						...common,
+						name: "product_list_view",
+						listId: input.listId,
+						productIds: input.productIds.slice(0, 100)
+					}, `list:${pageViewId}:${input.listId}`);
+					return;
+				case "search": push({
+					...common,
+					name: "search",
+					query: input.query.slice(0, 200),
+					resultCount: input.resultCount
+				}, `search:${pageViewId}:${input.query.trim().toLowerCase()}`);
+			}
+		},
+		page: startPage,
+		setConsent(next) {
+			consent = next;
+			if (next === "denied") queue = [];
+			if (next === "granted") {
+				if (pageViewId && !pageAccepted && options.autoPageViews !== false) {
+					pageKey = "";
+					startPage();
+				}
+				flush();
+			}
+		},
+		ids: () => enabled ? ensureIds() : null,
+		flush,
+		destroy() {
+			for (const cleanup of cleanups.splice(0)) cleanup();
+		}
+	};
+}
+const noopAnalytics = {
+	track() {},
+	page() {},
+	setConsent() {},
+	ids: () => null,
+	flush() {},
+	destroy() {}
+};
+function randomId() {
+	const bytes = /* @__PURE__ */ new Uint8Array(16);
+	crypto.getRandomValues(bytes);
+	let text = "";
+	for (const byte of bytes) text += String.fromCharCode(byte);
+	return btoa(text).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function browserEnv() {
+	return {
+		now: () => Date.now(),
+		href: () => location.href,
+		referrer: () => document.referrer,
+		hostname: () => location.hostname,
+		getCookie(name) {
+			for (const part of document.cookie.split(";")) {
+				const [key, ...rest] = part.trim().split("=");
+				if (key === name) return safeDecode(rest.join("="));
+			}
+			return null;
+		},
+		setCookie(name, value, maxAgeSec, domain) {
+			document.cookie = [
+				`${name}=${encodeURIComponent(value)}`,
+				"path=/",
+				`max-age=${maxAgeSec}`,
+				"samesite=lax",
+				...domain ? [`domain=${domain}`] : [],
+				...location.protocol === "https:" ? ["secure"] : []
+			].join("; ");
+		},
+		send(url, body) {
+			const blob = new Blob([body], { type: "text/plain;charset=UTF-8" });
+			if (typeof navigator.sendBeacon === "function" && navigator.sendBeacon(url, blob)) return;
+			fetch(url, {
+				method: "POST",
+				body,
+				keepalive: true,
+				credentials: "omit",
+				headers: { "content-type": "text/plain;charset=UTF-8" }
+			}).catch(() => {});
+		},
+		randomId,
+		visible: () => document.visibilityState !== "hidden",
+		prerendering: () => document.prerendering === true,
+		webdriver: () => navigator.webdriver === true,
+		on(event, fn) {
+			const target = event === "pagehide" ? window : document;
+			target.addEventListener(event, fn);
+			return () => target.removeEventListener(event, fn);
+		},
+		onNavigate(fn) {
+			const push = history.pushState;
+			const replace = history.replaceState;
+			history.pushState = function(...args) {
+				push.apply(this, args);
+				queueMicrotask(fn);
+			};
+			history.replaceState = function(...args) {
+				replace.apply(this, args);
+				queueMicrotask(fn);
+			};
+			window.addEventListener("popstate", fn);
+			return () => {
+				history.pushState = push;
+				history.replaceState = replace;
+				window.removeEventListener("popstate", fn);
+			};
+		},
+		setInterval(fn, ms) {
+			const id = window.setInterval(fn, ms);
+			return () => window.clearInterval(id);
+		}
+	};
+}
+//#endregion
+export { createAnalytics, createAnalyticsWith };

package/dist/analytics-ids-o0a07Ohr.mjs

@@ -0,0 +1,126 @@
+import { z } from "zod";
+//#region src/schemas/analytics.ts
+/**
+* 방문 분석 이벤트 계약 — 브라우저 모듈(`@sayren/storefront-sdk/analytics`)과 수집 엔드포인트
+* (`POST /storefront/v1/events`)가 같은 스키마를 쓴다.
+*
+* 행동 이벤트(페이지뷰·상품 조회·목록 노출·검색·체류)는 브라우저가 보낸다. 거래 이벤트(장바구니·결제 시작·구매)는
+* 스토어프론트 API가 요청을 처리하면서 서버에서 기록하므로 브라우저가 보내지 않는다 — 매출·전환은 조작이나
+* 누락이 없는 서버 데이터로 계산한다.
+*/
+/** 방문자·세션 식별자 — SDK가 만드는 URL-safe 난수 */
+const analyticsIdSchema = z.string().regex(/^[A-Za-z0-9_-]{16,64}$/);
+/** 방문자 ID 쿠키(1년) · 세션 ID 쿠키(30분 비활동) 이름. SSR 서버도 같은 이름으로 읽는다 */
+const ANALYTICS_VISITOR_COOKIE = "sy_vid";
+const ANALYTICS_SESSION_COOKIE = "sy_sid";
+/** 스토어프론트 API 요청에 실어 서버 거래 이벤트와 방문자·세션을 잇는 헤더 */
+const ANALYTICS_VISITOR_HEADER = "x-sayren-visitor";
+const ANALYTICS_SESSION_HEADER = "x-sayren-session";
+/** 브라우저가 보내는 이벤트 이름 */
+const analyticsClientEventNameSchema = z.enum([
+	"page_view",
+	"page_engagement",
+	"product_view",
+	"product_list_view",
+	"search"
+]);
+/** 서버가 기록하는 이벤트 이름 */
+const analyticsServerEventNameSchema = z.enum([
+	"add_to_cart",
+	"remove_from_cart",
+	"begin_checkout",
+	"purchase"
+]);
+const text = (max) => z.string().trim().min(1).max(max);
+const base = {
+	/** 발생 시각(ISO 8601). 서버가 수신 시각 ±24시간으로 보정한다 */
+	occurredAt: z.iso.datetime({ offset: true }),
+	/** 이벤트가 난 페이지의 전체 URL. 서버가 경로와 utm_*만 남기고 나머지 쿼리는 버린다 */
+	url: z.url().max(2048),
+	/** 한 페이지뷰 안의 이벤트를 묶는 난수. `page_engagement`가 어느 페이지뷰의 체류인지 가리킨다 */
+	pageViewId: analyticsIdSchema
+};
+const analyticsClientEventSchema = z.discriminatedUnion("name", [
+	z.object({
+		...base,
+		name: z.literal("page_view"),
+		/** document.referrer. 서버는 호스트만 남긴다 */
+		referrer: z.url().max(2048).optional()
+	}),
+	z.object({
+		...base,
+		name: z.literal("page_engagement"),
+		/** 페이지가 화면에 보인 누적 시간(ms) */
+		visibleMs: z.number().int().min(0).max(864e5)
+	}),
+	z.object({
+		...base,
+		name: z.literal("product_view"),
+		productId: text(64),
+		variantId: text(64).optional()
+	}),
+	z.object({
+		...base,
+		name: z.literal("product_list_view"),
+		/** 목록 식별자 — 예: `category:cat_123`, `search`, `home:new` */
+		listId: text(128),
+		productIds: z.array(text(64)).max(100)
+	}),
+	z.object({
+		...base,
+		name: z.literal("search"),
+		query: text(200),
+		resultCount: z.number().int().min(0)
+	})
+]);
+/** 한 번에 보내는 배치 — sendBeacon이라 헤더를 못 실어 테넌트·식별자를 본문에 싣는다 */
+const analyticsBatchSchema = z.object({
+	storeCode: text(64),
+	visitorId: analyticsIdSchema,
+	sessionId: analyticsIdSchema,
+	events: z.array(analyticsClientEventSchema).min(1).max(50),
+	/** 봇 판정 보조 신호 */
+	context: z.object({ 
+	/** navigator.webdriver — 자동화 브라우저 */
+webdriver: z.boolean().optional() }).optional()
+});
+/** 배치 본문 상한(바이트) — 서버가 넘는 요청을 거부한다 */
+const ANALYTICS_MAX_BATCH_BYTES = 32768;
+//#endregion
+//#region src/analytics-ids.ts
+/**
+* 요청의 Cookie 헤더에서 방문자·세션 ID를 읽는다 — SSR 서버가 스토어프론트 API를 부를 때 쓴다.
+* 브라우저 모듈(`@sayren/storefront-sdk/analytics`)이 셀러 도메인에 남긴 쿠키다. 형식이 틀린 값은 버린다.
+*
+* ```ts
+* const ids = analyticsIdsFromCookie(request.headers.get("cookie"));
+* createStorefrontClient({ baseUrl, storeCode, ...ids });
+* ```
+*/
+function analyticsIdsFromCookie(cookieHeader) {
+	if (!cookieHeader) return {};
+	const pick = (name) => {
+		for (const part of cookieHeader.split(";")) {
+			const [key, ...rest] = part.trim().split("=");
+			if (key !== name) continue;
+			const value = safeDecode(rest.join("="));
+			return value !== null && analyticsIdSchema.safeParse(value).success ? value : void 0;
+		}
+	};
+	const visitorId = pick(ANALYTICS_VISITOR_COOKIE);
+	const sessionId = pick(ANALYTICS_SESSION_COOKIE);
+	return {
+		...visitorId ? { visitorId } : {},
+		...sessionId ? { sessionId } : {}
+	};
+}
+/** 잘못된 퍼센트 인코딩(`%E0%A4`)은 URIError를 던진다 — 쿠키 하나 때문에 SSR 전체가 500이 되지 않게 버린다 */
+function safeDecode(value) {
+	try {
+		return decodeURIComponent(value);
+	} catch {
+		return null;
+	}
+}
+//#endregion
+export { ANALYTICS_SESSION_HEADER as a, analyticsBatchSchema as c, analyticsIdSchema as d, analyticsServerEventNameSchema as f, ANALYTICS_SESSION_COOKIE as i, analyticsClientEventNameSchema as l, safeDecode as n, ANALYTICS_VISITOR_COOKIE as o, ANALYTICS_MAX_BATCH_BYTES as r, ANALYTICS_VISITOR_HEADER as s, analyticsIdsFromCookie as t, analyticsClientEventSchema as u };

package/dist/index.d.mts

@@ -1,4 +1,19 @@
 import { z } from "zod";
+//#region src/analytics-ids.d.ts
+/**
+ * 요청의 Cookie 헤더에서 방문자·세션 ID를 읽는다 — SSR 서버가 스토어프론트 API를 부를 때 쓴다.
+ * 브라우저 모듈(`@sayren/storefront-sdk/analytics`)이 셀러 도메인에 남긴 쿠키다. 형식이 틀린 값은 버린다.
+ *
+ * ```ts
+ * const ids = analyticsIdsFromCookie(request.headers.get("cookie"));
+ * createStorefrontClient({ baseUrl, storeCode, ...ids });
+ * ```
+ */
+export declare function analyticsIdsFromCookie(cookieHeader: string | null | undefined): {
+  visitorId?: string;
+  sessionId?: string;
+};
+//#endregion
 //#region src/http.d.ts
 export declare class ApiError extends Error {
   readonly status: number;
@@ -674,6 +689,13 @@ interface StorefrontClientOptions {
   };
   /** 비회원 장바구니 토큰 */
   cartToken?: TokenSource;
+  /**
+   * 방문 분석 식별자 — 방문자·세션 ID(`sy_vid`·`sy_sid` 쿠키 값). 실으면 서버가 장바구니 담기·결제 시작·구매를
+   * 이 방문과 이어 기록한다. 브라우저는 `@sayren/storefront-sdk/analytics`의 `analytics.ids()`, SSR은
+   * `analyticsIdsFromCookie(request.headers.get("cookie"))`로 얻는다. 함수로 전달하면 매 요청마다 재평가.
+   */
+  visitorId?: TokenSource;
+  sessionId?: TokenSource;
   /** 서버가 새 X-Cart-Token을 발급했을 때 호출 */
   onCartToken?: (token: string) => void;
   /**
@@ -1276,6 +1298,123 @@ export declare function createStorefrontClient(options: StorefrontClientOptions)
 };
 type StorefrontClient = ReturnType<typeof createStorefrontClient>;
 //#endregion
+//#region src/schemas/analytics.d.ts
+/**
+ * 방문 분석 이벤트 계약 — 브라우저 모듈(`@sayren/storefront-sdk/analytics`)과 수집 엔드포인트
+ * (`POST /storefront/v1/events`)가 같은 스키마를 쓴다.
+ *
+ * 행동 이벤트(페이지뷰·상품 조회·목록 노출·검색·체류)는 브라우저가 보낸다. 거래 이벤트(장바구니·결제 시작·구매)는
+ * 스토어프론트 API가 요청을 처리하면서 서버에서 기록하므로 브라우저가 보내지 않는다 — 매출·전환은 조작이나
+ * 누락이 없는 서버 데이터로 계산한다.
+ */
+/** 방문자·세션 식별자 — SDK가 만드는 URL-safe 난수 */
+export declare const analyticsIdSchema: z.ZodString;
+/** 방문자 ID 쿠키(1년) · 세션 ID 쿠키(30분 비활동) 이름. SSR 서버도 같은 이름으로 읽는다 */
+export declare const ANALYTICS_VISITOR_COOKIE = "sy_vid";
+export declare const ANALYTICS_SESSION_COOKIE = "sy_sid";
+/** 스토어프론트 API 요청에 실어 서버 거래 이벤트와 방문자·세션을 잇는 헤더 */
+export declare const ANALYTICS_VISITOR_HEADER = "x-sayren-visitor";
+export declare const ANALYTICS_SESSION_HEADER = "x-sayren-session";
+/** 브라우저가 보내는 이벤트 이름 */
+export declare const analyticsClientEventNameSchema: z.ZodEnum<{
+  search: "search";
+  page_view: "page_view";
+  page_engagement: "page_engagement";
+  product_view: "product_view";
+  product_list_view: "product_list_view";
+}>;
+export type AnalyticsClientEventName = z.infer<typeof analyticsClientEventNameSchema>;
+/** 서버가 기록하는 이벤트 이름 */
+export declare const analyticsServerEventNameSchema: z.ZodEnum<{
+  add_to_cart: "add_to_cart";
+  remove_from_cart: "remove_from_cart";
+  begin_checkout: "begin_checkout";
+  purchase: "purchase";
+}>;
+export type AnalyticsServerEventName = z.infer<typeof analyticsServerEventNameSchema>;
+export type AnalyticsEventName = AnalyticsClientEventName | AnalyticsServerEventName;
+export declare const analyticsClientEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+  name: z.ZodLiteral<"page_view">;
+  referrer: z.ZodOptional<z.ZodURL>;
+  occurredAt: z.ZodISODateTime;
+  url: z.ZodURL;
+  pageViewId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+  name: z.ZodLiteral<"page_engagement">;
+  visibleMs: z.ZodNumber;
+  occurredAt: z.ZodISODateTime;
+  url: z.ZodURL;
+  pageViewId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+  name: z.ZodLiteral<"product_view">;
+  productId: z.ZodString;
+  variantId: z.ZodOptional<z.ZodString>;
+  occurredAt: z.ZodISODateTime;
+  url: z.ZodURL;
+  pageViewId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+  name: z.ZodLiteral<"product_list_view">;
+  listId: z.ZodString;
+  productIds: z.ZodArray<z.ZodString>;
+  occurredAt: z.ZodISODateTime;
+  url: z.ZodURL;
+  pageViewId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+  name: z.ZodLiteral<"search">;
+  query: z.ZodString;
+  resultCount: z.ZodNumber;
+  occurredAt: z.ZodISODateTime;
+  url: z.ZodURL;
+  pageViewId: z.ZodString;
+}, z.core.$strip>], "name">;
+export type AnalyticsClientEvent = z.infer<typeof analyticsClientEventSchema>;
+/** 한 번에 보내는 배치 — sendBeacon이라 헤더를 못 실어 테넌트·식별자를 본문에 싣는다 */
+export declare const analyticsBatchSchema: z.ZodObject<{
+  storeCode: z.ZodString;
+  visitorId: z.ZodString;
+  sessionId: z.ZodString;
+  events: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+    name: z.ZodLiteral<"page_view">;
+    referrer: z.ZodOptional<z.ZodURL>;
+    occurredAt: z.ZodISODateTime;
+    url: z.ZodURL;
+    pageViewId: z.ZodString;
+  }, z.core.$strip>, z.ZodObject<{
+    name: z.ZodLiteral<"page_engagement">;
+    visibleMs: z.ZodNumber;
+    occurredAt: z.ZodISODateTime;
+    url: z.ZodURL;
+    pageViewId: z.ZodString;
+  }, z.core.$strip>, z.ZodObject<{
+    name: z.ZodLiteral<"product_view">;
+    productId: z.ZodString;
+    variantId: z.ZodOptional<z.ZodString>;
+    occurredAt: z.ZodISODateTime;
+    url: z.ZodURL;
+    pageViewId: z.ZodString;
+  }, z.core.$strip>, z.ZodObject<{
+    name: z.ZodLiteral<"product_list_view">;
+    listId: z.ZodString;
+    productIds: z.ZodArray<z.ZodString>;
+    occurredAt: z.ZodISODateTime;
+    url: z.ZodURL;
+    pageViewId: z.ZodString;
+  }, z.core.$strip>, z.ZodObject<{
+    name: z.ZodLiteral<"search">;
+    query: z.ZodString;
+    resultCount: z.ZodNumber;
+    occurredAt: z.ZodISODateTime;
+    url: z.ZodURL;
+    pageViewId: z.ZodString;
+  }, z.core.$strip>], "name">>;
+  context: z.ZodOptional<z.ZodObject<{
+    webdriver: z.ZodOptional<z.ZodBoolean>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+export type AnalyticsBatch = z.infer<typeof analyticsBatchSchema>;
+/** 배치 본문 상한(바이트) — 서버가 넘는 요청을 거부한다 */
+export declare const ANALYTICS_MAX_BATCH_BYTES: number;
+//#endregion
 //#region src/schemas/order.d.ts
 export declare const myOrderItemSchema: z.ZodObject<{
   orderItemId: z.ZodString;

package/dist/index.mjs

@@ -1,3 +1,4 @@
+import { a as ANALYTICS_SESSION_HEADER, c as analyticsBatchSchema, d as analyticsIdSchema, f as analyticsServerEventNameSchema, i as ANALYTICS_SESSION_COOKIE, l as analyticsClientEventNameSchema, o as ANALYTICS_VISITOR_COOKIE, r as ANALYTICS_MAX_BATCH_BYTES, s as ANALYTICS_VISITOR_HEADER, t as analyticsIdsFromCookie, u as analyticsClientEventSchema } from "./analytics-ids-o0a07Ohr.mjs";
 import { z } from "zod";
 //#region src/http.ts
 /** 표준 엔벨로프의 $.error 상세 */
@@ -633,6 +634,10 @@ function createStorefrontClient(options) {
 			if (accessToken) headers.authorization = `Bearer ${accessToken}`;
 			const cartToken = resolveToken(options.cartToken);
 			if (cartToken) headers["x-cart-token"] = cartToken;
+			const visitorId = resolveToken(options.visitorId);
+			if (visitorId) headers[ANALYTICS_VISITOR_HEADER] = visitorId;
+			const sessionId = resolveToken(options.sessionId);
+			if (sessionId) headers[ANALYTICS_SESSION_HEADER] = sessionId;
 			return headers;
 		},
 		onResponse: (response) => {
@@ -877,4 +882,4 @@ function createStorefrontSession(options) {
 	};
 }
 //#endregion
-export { ApiError, PAYMENT_STATUS_VALUES, STOREFRONT_SESSION_KEYS, addCartItemRequestSchema, buildQuery, cartItemSchema, cartSchema, categoryNodeSchema, checkoutSessionSchema, claimReasonSchema, claimStatusSchema, claimTypeSchema, confirmPaymentRequestSchema, confirmPaymentResultSchema, createCheckoutRequestSchema, createClaimRequestSchema, createClaimResultSchema, createCustomerInquiryRequestSchema, createInquiryRequestSchema, createReviewRequestSchema, createReviewResultSchema, createStorefrontClient, createStorefrontSession, customerInquiryCategorySchema, customerInquirySchema, deliveryTrackingSchema, guestInfoSchema, loginRequestSchema, memberAddressRequestSchema, memberAddressSchema, memberSchema, myClaimSchema, myOrderItemSchema, myOrderSchema, orderItemStatusSchema, orderShippingAddressSchema, pageInfoSchema, pageSchema, paymentMethodSchema, paymentParamsSchema, paymentStatusSchema, pgParamsSchema, productCardSchema, productDetailSchema, productFacetsSchema, productSortSchema, publicInquirySchema, publicReviewSchema, requestPaymentRequestSchema, reviewSummarySchema, shippingAddressInputSchema, signupRequestSchema, tokenPairSchema, updateCartItemRequestSchema, updateProfileRequestSchema, updateReviewRequestSchema, writableReviewSchema };
+export { ANALYTICS_MAX_BATCH_BYTES, ANALYTICS_SESSION_COOKIE, ANALYTICS_SESSION_HEADER, ANALYTICS_VISITOR_COOKIE, ANALYTICS_VISITOR_HEADER, ApiError, PAYMENT_STATUS_VALUES, STOREFRONT_SESSION_KEYS, addCartItemRequestSchema, analyticsBatchSchema, analyticsClientEventNameSchema, analyticsClientEventSchema, analyticsIdSchema, analyticsIdsFromCookie, analyticsServerEventNameSchema, buildQuery, cartItemSchema, cartSchema, categoryNodeSchema, checkoutSessionSchema, claimReasonSchema, claimStatusSchema, claimTypeSchema, confirmPaymentRequestSchema, confirmPaymentResultSchema, createCheckoutRequestSchema, createClaimRequestSchema, createClaimResultSchema, createCustomerInquiryRequestSchema, createInquiryRequestSchema, createReviewRequestSchema, createReviewResultSchema, createStorefrontClient, createStorefrontSession, customerInquiryCategorySchema, customerInquirySchema, deliveryTrackingSchema, guestInfoSchema, loginRequestSchema, memberAddressRequestSchema, memberAddressSchema, memberSchema, myClaimSchema, myOrderItemSchema, myOrderSchema, orderItemStatusSchema, orderShippingAddressSchema, pageInfoSchema, pageSchema, paymentMethodSchema, paymentParamsSchema, paymentStatusSchema, pgParamsSchema, productCardSchema, productDetailSchema, productFacetsSchema, productSortSchema, publicInquirySchema, publicReviewSchema, requestPaymentRequestSchema, reviewSummarySchema, shippingAddressInputSchema, signupRequestSchema, tokenPairSchema, updateCartItemRequestSchema, updateProfileRequestSchema, updateReviewRequestSchema, writableReviewSchema };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sayren/storefront-sdk",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
   "exports": {
@@ -8,6 +8,11 @@
       "development": "./src/index.ts",
       "types": "./dist/index.d.mts",
       "default": "./dist/index.mjs"
+    },
+    "./analytics": {
+      "development": "./src/analytics/index.ts",
+      "types": "./dist/analytics/index.d.mts",
+      "default": "./dist/analytics/index.mjs"
     }
   },
   "dependencies": {
@@ -26,7 +31,7 @@
   "license": "UNLICENSED",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/cochoio/shop.24.git"
+    "url": "git+https://github.com/avarcorp/sayren.git"
   },
   "files": [
     "dist",

package/src/analytics/index.ts

@@ -0,0 +1,431 @@
+import { safeDecode } from "../analytics-ids";
+import {
+  ANALYTICS_SESSION_COOKIE,
+  ANALYTICS_VISITOR_COOKIE,
+  type AnalyticsBatch,
+  type AnalyticsClientEvent,
+} from "../schemas/analytics";
+
+/**
+ * 방문 분석 브라우저 모듈 — `@sayren/storefront-sdk/analytics`.
+ *
+ * 페이지뷰·상품 조회·목록 노출·검색·체류를 모아 배치로 보낸다. 장바구니·결제·구매는 스토어프론트 API가
+ * 서버에서 기록하므로 여기서 보내지 않는다(클라이언트에 `visitorId`·`sessionId`를 넘기면 이어진다).
+ *
+ * - 식별자는 셀러 도메인의 1st-party 쿠키(`sy_vid` 1년, `sy_sid` 30분 비활동)다. SSR 서버도 같은 쿠키를 읽는다.
+ * - 같은 행동은 한 번만 보낸다(StrictMode 이중 실행·리렌더 흡수). 서버도 결정적 id로 한 번 더 거른다.
+ * - 동의 전(`pending`)에는 쿠키를 만들지 않고 큐에만 쌓는다. `denied`면 버린다.
+ * - localhost·사설 IP에서는 기본으로 보내지 않는다(`debug: true`로 켠다).
+ */
+
+export type AnalyticsConsent = "granted" | "denied" | "pending";
+
+export interface AnalyticsOptions {
+  /** 스토어프론트 API 베이스 — 예: `https://api.sayren.app/storefront/v1` */
+  baseUrl: string;
+  /** 테넌트 스토어 코드 */
+  storeCode: string;
+  /** 동의 상태. 기본 `pending` — 셀러의 동의 배너가 `setConsent`로 바꾼다 */
+  consent?: AnalyticsConsent;
+  /** 페이지뷰를 자동으로 보낸다(첫 페이지 + History API 이동). 기본 true */
+  autoPageViews?: boolean;
+  /** 개발 호스트(localhost 등)에서도 보낸다. 기본 false */
+  debug?: boolean;
+  /** 쿠키 도메인 — 서브도메인끼리 방문자를 공유하려면 `.myshop.com` */
+  cookieDomain?: string;
+  /** 배치 전송 간격(ms). 기본 5000 */
+  flushIntervalMs?: number;
+}
+
+export type AnalyticsTrackInput =
+  | { name: "product_view"; productId: string; variantId?: string }
+  | { name: "product_list_view"; listId: string; productIds: string[] }
+  | { name: "search"; query: string; resultCount: number };
+
+export interface Analytics {
+  /** 행동 이벤트 — 같은 페이지뷰 안의 같은 행동은 한 번만 보낸다 */
+  track(input: AnalyticsTrackInput): void;
+  /** 페이지뷰를 직접 보낸다(`autoPageViews: false`일 때) */
+  page(): void;
+  setConsent(consent: AnalyticsConsent): void;
+  /** 방문자·세션 ID — `createStorefrontClient({ visitorId, sessionId })`에 넘긴다. 동의 전·거부면 null */
+  ids(): { visitorId: string; sessionId: string } | null;
+  /** 큐를 지금 보낸다 */
+  flush(): void;
+  /** 리스너·타이머를 걷는다 */
+  destroy(): void;
+}
+
+/** 브라우저 의존부 — 테스트는 가짜 환경을 넣는다 */
+export interface AnalyticsEnv {
+  now(): number;
+  href(): string;
+  referrer(): string;
+  hostname(): string;
+  getCookie(name: string): string | null;
+  setCookie(name: string, value: string, maxAgeSec: number, domain?: string): void;
+  /** 배치를 보낸다(sendBeacon, 안 되면 fetch keepalive) */
+  send(url: string, body: string): void;
+  randomId(): string;
+  visible(): boolean;
+  prerendering(): boolean;
+  webdriver(): boolean;
+  /** 이벤트 리스너를 달고 떼는 함수를 돌려준다 */
+  on(event: "visibilitychange" | "pagehide" | "prerenderingchange", fn: () => void): () => void;
+  /** History API 이동(pushState·replaceState·popstate)을 구독한다 */
+  onNavigate(fn: () => void): () => void;
+  setInterval(fn: () => void, ms: number): () => void;
+}
+
+const VISITOR_MAX_AGE_SEC = 365 * 24 * 3600;
+const SESSION_MAX_AGE_SEC = 30 * 60;
+/** 세션을 시작한 캠페인 — 다른 캠페인으로 들어오면 새 세션이다 */
+const SESSION_CAMPAIGN_COOKIE = "sy_scmp";
+const MAX_BATCH = 50;
+/** 이벤트 이름당 분당 상한 — 무한 루프 버그가 트래픽을 만들지 못하게 */
+const PER_NAME_PER_MINUTE = 30;
+/**
+ * 전체 분당 상한 — 서버의 방문자당 분당 한도(120)보다 낮게 둬, SDK가 보낸 이벤트가 서버 한도에 걸려
+ * 조용히 버려지지 않게 한다(이름당 상한만으로는 이름 5종 × 30 = 150까지 갈 수 있다).
+ */
+const TOTAL_PER_MINUTE = 100;
+const MAX_QUEUE = 500;
+
+const DEV_HOST =
+  /^(localhost|127\.\d+\.\d+\.\d+|\[?::1\]?|0\.0\.0\.0|10\.\d+\.\d+\.\d+|192\.168\.\d+\.\d+|172\.(1[6-9]|2\d|3[01])\.\d+\.\d+)$|\.local$/i;
+
+type Pending = AnalyticsClientEvent;
+
+export function createAnalytics(options: AnalyticsOptions): Analytics {
+  if (typeof window === "undefined" || typeof document === "undefined") return noopAnalytics;
+  return createAnalyticsWith(options, browserEnv());
+}
+
+/** 테스트·비표준 런타임용 — 환경을 직접 넣는다 */
+export function createAnalyticsWith(options: AnalyticsOptions, env: AnalyticsEnv): Analytics {
+  const endpoint = `${options.baseUrl.replace(/\/+$/, "")}/events`;
+  const enabled = options.debug === true || !DEV_HOST.test(env.hostname());
+  let consent: AnalyticsConsent = options.consent ?? "pending";
+  let queue: Pending[] = [];
+  let pageViewId = "";
+  let pageKey = "";
+  /** 지금 페이지뷰의 URL — SPA 이동 뒤 이전 페이지의 체류를 보낼 때 새 URL과 섞이지 않게 */
+  let pageHref = "";
+  let visibleSince: number | null = null;
+  let visibleMs = 0;
+  let engagementSent = false;
+  let firstPage = true;
+  /**
+   * 지금 페이지뷰를 보냈는가 — 상한으로 페이지뷰가 버려졌으면 그 페이지의 상품 조회·목록·검색·체류도 보내지 않는다.
+   * 그러지 않으면 존재하지 않는 페이지뷰를 가리키는 이벤트가 남는다.
+   */
+  let pageAccepted = false;
+  const seen = new Set<string>();
+  let rateMinute = -1;
+  const perName = new Map<string, number>();
+  let totalThisMinute = 0;
+  const cleanups: Array<() => void> = [];
+
+  const campaignOf = (href: string) => {
+    try {
+      const params = new URL(href).searchParams;
+      const source = params.get("utm_source");
+      return source ? `${source}|${params.get("utm_campaign") ?? ""}` : null;
+    } catch {
+      return null;
+    }
+  };
+
+  /** 동의가 있을 때만 쿠키를 읽고 만든다. 세션은 이벤트마다 30분 연장한다 */
+  const ensureIds = (): { visitorId: string; sessionId: string } | null => {
+    if (consent !== "granted") return null;
+    let visitorId = env.getCookie(ANALYTICS_VISITOR_COOKIE);
+    if (!visitorId) visitorId = env.randomId();
+    let sessionId = env.getCookie(ANALYTICS_SESSION_COOKIE);
+    const campaign = campaignOf(env.href());
+    if (campaign && campaign !== env.getCookie(SESSION_CAMPAIGN_COOKIE)) {
+      sessionId = null; // 새 캠페인으로 들어왔다 — 새 세션
+      env.setCookie(SESSION_CAMPAIGN_COOKIE, campaign, SESSION_MAX_AGE_SEC, options.cookieDomain);
+    }
+    if (!sessionId) sessionId = env.randomId();
+    env.setCookie(ANALYTICS_VISITOR_COOKIE, visitorId, VISITOR_MAX_AGE_SEC, options.cookieDomain);
+    env.setCookie(ANALYTICS_SESSION_COOKIE, sessionId, SESSION_MAX_AGE_SEC, options.cookieDomain);
+    return { visitorId, sessionId };
+  };
+
+  const allowRate = (name: string) => {
+    const minute = Math.floor(env.now() / 60_000);
+    if (minute !== rateMinute) {
+      rateMinute = minute;
+      perName.clear();
+      totalThisMinute = 0;
+    }
+    const used = perName.get(name) ?? 0;
+    if (used >= PER_NAME_PER_MINUTE || totalThisMinute >= TOTAL_PER_MINUTE) return false;
+    perName.set(name, used + 1);
+    totalThisMinute += 1;
+    return true;
+  };
+
+  /** 큐에 넣었으면 true — 중복·상한·거부로 버리면 false */
+  const push = (event: Pending, dedupeKey: string): boolean => {
+    if (!enabled || consent === "denied") return false;
+    if (seen.has(dedupeKey) || !allowRate(event.name)) return false;
+    seen.add(dedupeKey);
+    if (queue.length >= MAX_QUEUE) queue.shift();
+    queue.push(event);
+    if (queue.length >= MAX_BATCH) flush();
+    return true;
+  };
+
+  const flush = () => {
+    if (!enabled || queue.length === 0) return;
+    const ids = ensureIds();
+    if (!ids) return; // 동의 전 — 큐에 둔다
+    while (queue.length > 0) {
+      const events = queue.splice(0, MAX_BATCH) as AnalyticsClientEvent[];
+      const batch: AnalyticsBatch = {
+        storeCode: options.storeCode,
+        ...ids,
+        events,
+        ...(env.webdriver() ? { context: { webdriver: true } } : {}),
+      };
+      env.send(endpoint, JSON.stringify(batch));
+    }
+  };
+
+  const occurredAt = () => new Date(env.now()).toISOString();
+
+  /** 지금 페이지의 체류를 한 번 보낸다(이동·숨김·닫힘 중 먼저 오는 때) */
+  const endPage = () => {
+    if (!pageViewId || engagementSent || !pageAccepted) return;
+    if (visibleSince !== null) {
+      visibleMs += env.now() - visibleSince;
+      visibleSince = env.visible() ? env.now() : null;
+    }
+    engagementSent = true;
+    push(
+      {
+        name: "page_engagement",
+        occurredAt: occurredAt(),
+        url: pageHref,
+        pageViewId,
+        visibleMs: Math.max(0, Math.round(visibleMs)),
+      },
+      `engagement:${pageViewId}`,
+    );
+  };
+
+  const startPage = () => {
+    const href = env.href();
+    let key = href;
+    try {
+      const url = new URL(href);
+      key = `${url.pathname}${url.search}`; // 해시만 바뀐 이동은 새 페이지가 아니다
+    } catch {
+      // 그대로 쓴다
+    }
+    if (key === pageKey) return;
+    endPage();
+    pageKey = key;
+    pageHref = href;
+    pageViewId = env.randomId();
+    visibleMs = 0;
+    visibleSince = env.visible() ? env.now() : null;
+    engagementSent = false;
+    const referrer = firstPage ? env.referrer() : "";
+    pageAccepted = push(
+      {
+        name: "page_view",
+        occurredAt: occurredAt(),
+        url: href,
+        pageViewId,
+        ...(referrer ? { referrer } : {}),
+      },
+      `page:${pageViewId}`,
+    );
+    // 외부 유입(리퍼러)은 실제로 보낸 첫 페이지뷰에만 싣는다 — 거부 중 버린 페이지뷰가 가져가지 않게
+    if (pageAccepted) firstPage = false;
+  };
+
+  /** 프리렌더·숨은 탭은 화면에 보이는 순간 첫 페이지뷰를 보낸다 */
+  const startWhenVisible = () => {
+    if (!env.prerendering() && env.visible()) {
+      startPage();
+      return;
+    }
+    const tryStart = () => {
+      if (!pageViewId && !env.prerendering() && env.visible()) startPage();
+    };
+    cleanups.push(env.on("prerenderingchange", tryStart), env.on("visibilitychange", tryStart));
+  };
+
+  cleanups.push(
+    env.on("visibilitychange", () => {
+      if (env.visible()) {
+        if (pageViewId && visibleSince === null) visibleSince = env.now();
+        return;
+      }
+      endPage();
+      flush();
+    }),
+    env.on("pagehide", () => {
+      endPage();
+      flush();
+    }),
+    env.setInterval(flush, options.flushIntervalMs ?? 5_000),
+  );
+
+  if (options.autoPageViews !== false) {
+    startWhenVisible();
+    cleanups.push(env.onNavigate(startPage));
+  }
+
+  return {
+    track(input) {
+      if (!pageViewId) startPage();
+      if (!pageAccepted) return; // 페이지뷰가 버려진 페이지의 행동은 보내지 않는다
+      const common = { occurredAt: occurredAt(), url: env.href(), pageViewId };
+      switch (input.name) {
+        case "product_view":
+          push(
+            {
+              ...common,
+              name: "product_view",
+              productId: input.productId,
+              ...(input.variantId ? { variantId: input.variantId } : {}),
+            },
+            `product:${pageViewId}:${input.productId}`,
+          );
+          return;
+        case "product_list_view":
+          push(
+            {
+              ...common,
+              name: "product_list_view",
+              listId: input.listId,
+              productIds: input.productIds.slice(0, 100),
+            },
+            `list:${pageViewId}:${input.listId}`,
+          );
+          return;
+        case "search":
+          push(
+            {
+              ...common,
+              name: "search",
+              query: input.query.slice(0, 200),
+              resultCount: input.resultCount,
+            },
+            `search:${pageViewId}:${input.query.trim().toLowerCase()}`,
+          );
+      }
+    },
+    page: startPage,
+    setConsent(next) {
+      consent = next;
+      if (next === "denied") queue = [];
+      if (next === "granted") {
+        // 거부 중에 연 페이지는 페이지뷰가 없다 — 동의한 지금 그 페이지를 새로 센다
+        if (pageViewId && !pageAccepted && options.autoPageViews !== false) {
+          pageKey = "";
+          startPage();
+        }
+        flush();
+      }
+    },
+    ids: () => (enabled ? ensureIds() : null),
+    flush,
+    destroy() {
+      for (const cleanup of cleanups.splice(0)) cleanup();
+    },
+  };
+}
+
+const noopAnalytics: Analytics = {
+  track() {},
+  page() {},
+  setConsent() {},
+  ids: () => null,
+  flush() {},
+  destroy() {},
+};
+
+function randomId(): string {
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  let text = "";
+  for (const byte of bytes) text += String.fromCharCode(byte);
+  return btoa(text).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function browserEnv(): AnalyticsEnv {
+  return {
+    now: () => Date.now(),
+    href: () => location.href,
+    referrer: () => document.referrer,
+    hostname: () => location.hostname,
+    getCookie(name) {
+      for (const part of document.cookie.split(";")) {
+        const [key, ...rest] = part.trim().split("=");
+        if (key === name) return safeDecode(rest.join("="));
+      }
+      return null;
+    },
+    setCookie(name, value, maxAgeSec, domain) {
+      // biome-ignore lint/suspicious/noDocumentCookie: 방문 식별자는 SSR 서버도 읽어야 해서 1st-party 쿠키에 둔다
+      document.cookie = [
+        `${name}=${encodeURIComponent(value)}`,
+        "path=/",
+        `max-age=${maxAgeSec}`,
+        "samesite=lax",
+        ...(domain ? [`domain=${domain}`] : []),
+        ...(location.protocol === "https:" ? ["secure"] : []),
+      ].join("; ");
+    },
+    send(url, body) {
+      // text/plain은 CORS 프리플라이트가 없다. 페이지를 떠나는 순간에도 전송된다
+      const blob = new Blob([body], { type: "text/plain;charset=UTF-8" });
+      if (typeof navigator.sendBeacon === "function" && navigator.sendBeacon(url, blob)) return;
+      void fetch(url, {
+        method: "POST",
+        body,
+        keepalive: true,
+        credentials: "omit",
+        headers: { "content-type": "text/plain;charset=UTF-8" },
+      }).catch(() => {});
+    },
+    randomId,
+    visible: () => document.visibilityState !== "hidden",
+    prerendering: () => (document as Document & { prerendering?: boolean }).prerendering === true,
+    webdriver: () => navigator.webdriver === true,
+    on(event, fn) {
+      const target: EventTarget = event === "pagehide" ? window : document;
+      target.addEventListener(event, fn);
+      return () => target.removeEventListener(event, fn);
+    },
+    onNavigate(fn) {
+      // pushState·replaceState는 이벤트가 없어 감싼다. 원래 함수는 해제 때 되돌린다
+      const push = history.pushState;
+      const replace = history.replaceState;
+      history.pushState = function (...args: Parameters<History["pushState"]>) {
+        push.apply(this, args);
+        queueMicrotask(fn);
+      };
+      history.replaceState = function (...args: Parameters<History["replaceState"]>) {
+        replace.apply(this, args);
+        queueMicrotask(fn);
+      };
+      window.addEventListener("popstate", fn);
+      return () => {
+        history.pushState = push;
+        history.replaceState = replace;
+        window.removeEventListener("popstate", fn);
+      };
+    },
+    setInterval(fn, ms) {
+      const id = window.setInterval(fn, ms);
+      return () => window.clearInterval(id);
+    },
+  };
+}

package/src/analytics-ids.ts

@@ -0,0 +1,42 @@
+import {
+  ANALYTICS_SESSION_COOKIE,
+  ANALYTICS_VISITOR_COOKIE,
+  analyticsIdSchema,
+} from "./schemas/analytics";
+
+/**
+ * 요청의 Cookie 헤더에서 방문자·세션 ID를 읽는다 — SSR 서버가 스토어프론트 API를 부를 때 쓴다.
+ * 브라우저 모듈(`@sayren/storefront-sdk/analytics`)이 셀러 도메인에 남긴 쿠키다. 형식이 틀린 값은 버린다.
+ *
+ * ```ts
+ * const ids = analyticsIdsFromCookie(request.headers.get("cookie"));
+ * createStorefrontClient({ baseUrl, storeCode, ...ids });
+ * ```
+ */
+export function analyticsIdsFromCookie(cookieHeader: string | null | undefined): {
+  visitorId?: string;
+  sessionId?: string;
+} {
+  if (!cookieHeader) return {};
+  const pick = (name: string) => {
+    for (const part of cookieHeader.split(";")) {
+      const [key, ...rest] = part.trim().split("=");
+      if (key !== name) continue;
+      const value = safeDecode(rest.join("="));
+      return value !== null && analyticsIdSchema.safeParse(value).success ? value : undefined;
+    }
+    return undefined;
+  };
+  const visitorId = pick(ANALYTICS_VISITOR_COOKIE);
+  const sessionId = pick(ANALYTICS_SESSION_COOKIE);
+  return { ...(visitorId ? { visitorId } : {}), ...(sessionId ? { sessionId } : {}) };
+}
+
+/** 잘못된 퍼센트 인코딩(`%E0%A4`)은 URIError를 던진다 — 쿠키 하나 때문에 SSR 전체가 500이 되지 않게 버린다 */
+export function safeDecode(value: string): string | null {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return null;
+  }
+}

package/src/client.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { createHttp, path, type Query, resolveToken, type TokenSource } from "./http";
+import { ANALYTICS_SESSION_HEADER, ANALYTICS_VISITOR_HEADER } from "./schemas/analytics";
 import type { LoginRequest, SignupRequest } from "./schemas/auth";
 import { loginRequestSchema, signupRequestSchema, tokenPairSchema } from "./schemas/auth";
 import {
@@ -85,6 +86,13 @@ export interface StorefrontClientOptions {
   auth?: { accessToken?: string };
   /** 비회원 장바구니 토큰 */
   cartToken?: TokenSource;
+  /**
+   * 방문 분석 식별자 — 방문자·세션 ID(`sy_vid`·`sy_sid` 쿠키 값). 실으면 서버가 장바구니 담기·결제 시작·구매를
+   * 이 방문과 이어 기록한다. 브라우저는 `@sayren/storefront-sdk/analytics`의 `analytics.ids()`, SSR은
+   * `analyticsIdsFromCookie(request.headers.get("cookie"))`로 얻는다. 함수로 전달하면 매 요청마다 재평가.
+   */
+  visitorId?: TokenSource;
+  sessionId?: TokenSource;
   /** 서버가 새 X-Cart-Token을 발급했을 때 호출 */
   onCartToken?: (token: string) => void;
   /**
@@ -126,6 +134,10 @@ export function createStorefrontClient(options: StorefrontClientOptions) {
       if (accessToken) headers.authorization = `Bearer ${accessToken}`;
       const cartToken = resolveToken(options.cartToken);
       if (cartToken) headers["x-cart-token"] = cartToken;
+      const visitorId = resolveToken(options.visitorId);
+      if (visitorId) headers[ANALYTICS_VISITOR_HEADER] = visitorId;
+      const sessionId = resolveToken(options.sessionId);
+      if (sessionId) headers[ANALYTICS_SESSION_HEADER] = sessionId;
       return headers;
     },
     onResponse: (response) => {

package/src/index.ts

@@ -1,7 +1,9 @@
+export { analyticsIdsFromCookie } from "./analytics-ids";
 export type { StorefrontClient, StorefrontClientOptions } from "./client";
 export { createStorefrontClient } from "./client";
 export type { Query, TokenSource } from "./http";
 export { ApiError, buildQuery } from "./http";
+export * from "./schemas/analytics";
 export * from "./schemas/auth";
 export * from "./schemas/cart";
 export * from "./schemas/catalog";

package/src/schemas/analytics.ts

@@ -0,0 +1,111 @@
+import { z } from "zod";
+
+/**
+ * 방문 분석 이벤트 계약 — 브라우저 모듈(`@sayren/storefront-sdk/analytics`)과 수집 엔드포인트
+ * (`POST /storefront/v1/events`)가 같은 스키마를 쓴다.
+ *
+ * 행동 이벤트(페이지뷰·상품 조회·목록 노출·검색·체류)는 브라우저가 보낸다. 거래 이벤트(장바구니·결제 시작·구매)는
+ * 스토어프론트 API가 요청을 처리하면서 서버에서 기록하므로 브라우저가 보내지 않는다 — 매출·전환은 조작이나
+ * 누락이 없는 서버 데이터로 계산한다.
+ */
+
+/** 방문자·세션 식별자 — SDK가 만드는 URL-safe 난수 */
+export const analyticsIdSchema = z.string().regex(/^[A-Za-z0-9_-]{16,64}$/);
+
+/** 방문자 ID 쿠키(1년) · 세션 ID 쿠키(30분 비활동) 이름. SSR 서버도 같은 이름으로 읽는다 */
+export const ANALYTICS_VISITOR_COOKIE = "sy_vid";
+export const ANALYTICS_SESSION_COOKIE = "sy_sid";
+
+/** 스토어프론트 API 요청에 실어 서버 거래 이벤트와 방문자·세션을 잇는 헤더 */
+export const ANALYTICS_VISITOR_HEADER = "x-sayren-visitor";
+export const ANALYTICS_SESSION_HEADER = "x-sayren-session";
+
+/** 브라우저가 보내는 이벤트 이름 */
+export const analyticsClientEventNameSchema = z.enum([
+  "page_view",
+  "page_engagement",
+  "product_view",
+  "product_list_view",
+  "search",
+]);
+export type AnalyticsClientEventName = z.infer<typeof analyticsClientEventNameSchema>;
+
+/** 서버가 기록하는 이벤트 이름 */
+export const analyticsServerEventNameSchema = z.enum([
+  "add_to_cart",
+  "remove_from_cart",
+  "begin_checkout",
+  "purchase",
+]);
+export type AnalyticsServerEventName = z.infer<typeof analyticsServerEventNameSchema>;
+
+export type AnalyticsEventName = AnalyticsClientEventName | AnalyticsServerEventName;
+
+const text = (max: number) => z.string().trim().min(1).max(max);
+
+const base = {
+  /** 발생 시각(ISO 8601). 서버가 수신 시각 ±24시간으로 보정한다 */
+  occurredAt: z.iso.datetime({ offset: true }),
+  /** 이벤트가 난 페이지의 전체 URL. 서버가 경로와 utm_*만 남기고 나머지 쿼리는 버린다 */
+  url: z.url().max(2048),
+  /** 한 페이지뷰 안의 이벤트를 묶는 난수. `page_engagement`가 어느 페이지뷰의 체류인지 가리킨다 */
+  pageViewId: analyticsIdSchema,
+};
+
+export const analyticsClientEventSchema = z.discriminatedUnion("name", [
+  z.object({
+    ...base,
+    name: z.literal("page_view"),
+    /** document.referrer. 서버는 호스트만 남긴다 */
+    referrer: z.url().max(2048).optional(),
+  }),
+  z.object({
+    ...base,
+    name: z.literal("page_engagement"),
+    /** 페이지가 화면에 보인 누적 시간(ms) */
+    visibleMs: z
+      .number()
+      .int()
+      .min(0)
+      .max(24 * 3_600_000),
+  }),
+  z.object({
+    ...base,
+    name: z.literal("product_view"),
+    productId: text(64),
+    variantId: text(64).optional(),
+  }),
+  z.object({
+    ...base,
+    name: z.literal("product_list_view"),
+    /** 목록 식별자 — 예: `category:cat_123`, `search`, `home:new` */
+    listId: text(128),
+    productIds: z.array(text(64)).max(100),
+  }),
+  z.object({
+    ...base,
+    name: z.literal("search"),
+    query: text(200),
+    resultCount: z.number().int().min(0),
+  }),
+]);
+export type AnalyticsClientEvent = z.infer<typeof analyticsClientEventSchema>;
+
+/** 한 번에 보내는 배치 — sendBeacon이라 헤더를 못 실어 테넌트·식별자를 본문에 싣는다 */
+export const analyticsBatchSchema = z.object({
+  storeCode: text(64),
+  visitorId: analyticsIdSchema,
+  sessionId: analyticsIdSchema,
+  events: z.array(analyticsClientEventSchema).min(1).max(50),
+  /** 봇 판정 보조 신호 */
+  context: z
+    .object({
+      /** navigator.webdriver — 자동화 브라우저 */
+      webdriver: z.boolean().optional(),
+    })
+    .optional(),
+});
+export type AnalyticsBatch = z.infer<typeof analyticsBatchSchema>;
+
+/** 배치 본문 상한(바이트) — 서버가 넘는 요청을 거부한다 */
+export const ANALYTICS_MAX_BATCH_BYTES = 32 * 1024;