@sayren/mcp 0.1.1 → 0.1.3

package/dist/index.mjs

@@ -529,6 +529,16 @@ const RULES = [
 		title: "팝업 메시지는 origin과 source를 모두 검증한다",
 		why: "검증 없이 받으면 아무 창이나 결제 완료를 흉내 낼 수 있다"
 	},
+	{
+		id: "analytics-start",
+		title: "방문 분석은 브라우저에서 한 번 시작한다(`@sayren/storefront-sdk/analytics`)",
+		why: "빠지면 셀러 콘솔 애널리틱스가 비어 있다. 서버 파일에서 부르면 아무것도 하지 않는다"
+	},
+	{
+		id: "analytics-ids",
+		title: "서버의 API 클라이언트에 방문 식별 쿠키를 싣는다(`analyticsIdsFromCookie`)",
+		why: "빠지면 장바구니·결제 시작·구매가 방문과 이어지지 않아 퍼널과 유입별 매출에서 빠진다"
+	},
 	{
 		id: "closed-not-failed",
 		title: "팝업이 결과 없이 닫히면 실패로 단정하지 않는다",
@@ -543,7 +553,7 @@ const CLIENT_FILE = /\.(ts|tsx)$/;
 const SERVER_FILE = /\.server\.(ts|tsx)$/;
 /**
 * 만들어진 프로젝트의 소스를 규칙과 대조한다. 정적 검사라 모든 문제를 잡지는 못하지만,
-* 이 아홉 가지는 실제로 반복해서 깨지는 것들이다.
+* 여기 있는 것들은 실제로 반복해서 깨지는 것들이다.
 */
 function verifySources(files) {
 	const findings = [];
@@ -554,7 +564,8 @@ function verifySources(files) {
 	const has = (needle) => cleaned.some((file) => file.content.includes(needle));
 	for (const file of cleaned) {
 		if (!CLIENT_FILE.test(file.path)) continue;
-		if (!(SERVER_FILE.test(file.path) || /\/(server|\.server)\//.test(file.path)) && /process\.env\.[A-Z_]/.test(file.content)) findings.push({
+		const isServer = SERVER_FILE.test(file.path) || /\/(server|\.server)\//.test(file.path);
+		if (!isServer && /process\.env\.[A-Z_]/.test(file.content)) findings.push({
 			ruleId: "server-only-env",
 			file: file.path,
 			detail: "브라우저로 갈 수 있는 파일에서 process.env를 읽는다. `*.server.ts`로 옮긴다"
@@ -586,6 +597,16 @@ function verifySources(files) {
 				detail: "message 리스너가 source(우리가 연 창)를 검증하지 않는다"
 			});
 		}
+		if (isServer && /createAnalytics\(/.test(file.content)) findings.push({
+			ruleId: "analytics-start",
+			file: file.path,
+			detail: "서버 파일에서 방문 분석을 시작한다. 서버에서는 아무것도 하지 않으니 브라우저(effect)에서 부른다"
+		});
+		if (isServer && /createStorefrontClient\(/.test(file.content) && !/analyticsIdsFromCookie|visitorId/.test(file.content)) findings.push({
+			ruleId: "analytics-ids",
+			file: file.path,
+			detail: "서버 API 클라이언트에 방문 식별자가 없다. `...analyticsIdsFromCookie(request.headers.get(\"cookie\"))`를 넘긴다"
+		});
 		if (/requestPayment\(/.test(file.content) && /<form\s/.test(file.content)) findings.push({
 			ruleId: "popup-client-submit",
 			file: file.path,
@@ -602,6 +623,11 @@ function verifySources(files) {
 		file: "(프로젝트 전체)",
 		detail: "팝업이 결과 없이 닫힌 경우 결제 상태를 조회하는 코드가 없다"
 	});
+	if (has("createStorefrontClient(") && !has("@sayren/storefront-sdk/analytics")) findings.push({
+		ruleId: "analytics-start",
+		file: "(프로젝트 전체)",
+		detail: "방문 분석을 시작하는 코드가 없다. `@sayren/storefront-sdk/analytics`의 createAnalytics를 브라우저에서 한 번 부른다"
+	});
 	if (has("createStorefrontClient(") && !has("loader")) findings.push({
 		ruleId: "loader-first",
 		file: "(프로젝트 전체)",
@@ -674,7 +700,8 @@ server.registerTool("get_scaffold_plan", {
 		],
 		doNotTouch: [
 			"app/lib/payment-popup.ts — 결제 팝업 규칙",
-			"app/lib/api.server.ts — 테넌트 헤더·토큰 전달·부모 origin",
+			"app/lib/api.server.ts — 테넌트 헤더·토큰 전달·부모 origin·방문 식별 쿠키",
+			"app/lib/analytics.ts — 방문 분석 시작(브라우저 한 번)과 시작 전 이벤트 큐",
 			"loader에서 데이터를 받는 구조"
 		],
 		rules: RULES,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sayren/mcp",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "bin": {
     "sayren-mcp": "./dist/index.mjs"
@@ -12,8 +12,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.22.0",
     "zod": "^4.6.5",
-    "@sayren/store-sdk": "^0.1.1",
-    "@sayren/storefront-sdk": "^0.1.0"
+    "@sayren/store-sdk": "^0.3.0",
+    "@sayren/storefront-sdk": "^0.2.1"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.14",

package/template/.template-meta.json

@@ -7,8 +7,8 @@
     "zod": "^4.6.5"
   },
   "versions": {
-    "@sayren/store-sdk": "0.1.1",
-    "@sayren/storefront-sdk": "0.1.0",
+    "@sayren/store-sdk": "0.3.0",
+    "@sayren/storefront-sdk": "0.2.1",
     "@sayren/ui": "0.1.0"
   }
 }

package/template/README.md

@@ -16,10 +16,18 @@ pnpm dev
 | --- | --- |
 | `SAYREN_API_URL` | 스토어프론트 API 베이스 |
 | `SAYREN_STORE_CODE` | 테넌트 스토어 코드. 서브도메인으로 서비스하면 비워 둔다 |
+| `SAYREN_ANALYTICS_DEBUG` | `1`이면 localhost에서도 방문 분석을 보낸다 |
 
 `pnpm dev`는 프로젝트 루트의 `.env`에서 `SAYREN_*`를 읽는다. 셸에서 준 값이 우선한다.
 `pnpm start`(빌드 결과 실행)는 `.env`를 읽지 않으므로 환경변수로 넘긴다.
 
+## 방문 분석
+
+`app/lib/analytics.ts`가 브라우저에서 방문 분석을 시작한다. 페이지뷰·체류는 자동으로 세고, 상품 조회·목록 노출·검색은
+화면에서 `useTrack`으로 남긴다. 장바구니·결제·구매는 `app/lib/api.server.ts`가 방문자 쿠키를 API 요청 헤더에 실어
+서버가 기록한다. localhost에서는 보내지 않는다. 개발 중에 확인하려면 `SAYREN_ANALYTICS_DEBUG=1`을 준다.
+쿠키 동의 배너를 붙인다면 `consent`를 `"pending"`으로 바꾸고 배너에서 `setConsent`를 부른다.
+
 ## 확장 지점
 
 | 자리 | 파일 |

package/template/app/lib/analytics.ts

@@ -0,0 +1,60 @@
+import {
+  type Analytics,
+  type AnalyticsOptions,
+  type AnalyticsTrackInput,
+  createAnalytics,
+} from "@sayren/storefront-sdk/analytics";
+import { useEffect } from "react";
+
+/**
+ * 방문 분석 — 브라우저 전용. 루트가 한 번 시작하고, 화면은 `useTrack`으로 행동을 남긴다.
+ *
+ * 장바구니·결제 시작·구매는 여기서 보내지 않는다. 스토어프론트 API가 요청을 처리하면서 서버에서
+ * 기록한다(`api.server.ts`가 방문자·세션 쿠키를 헤더로 싣는다).
+ */
+
+/** 루트 loader가 내려주는 값 */
+export interface AnalyticsConfig {
+  apiBaseUrl: string;
+  storeCode: string;
+  /** localhost에서도 보낸다(`SAYREN_ANALYTICS_DEBUG=1`) */
+  debug: boolean;
+}
+
+let instance: Analytics | null = null;
+/**
+ * 시작 전에 들어온 행동. React는 자식 effect를 부모보다 먼저 돌리므로 첫 화면의 `useTrack`이
+ * 루트의 시작보다 앞선다.
+ */
+let pending: AnalyticsTrackInput[] = [];
+
+export function startAnalytics(config: AnalyticsConfig): Analytics {
+  if (instance) return instance;
+  const options: AnalyticsOptions = {
+    baseUrl: config.apiBaseUrl,
+    storeCode: config.storeCode,
+    debug: config.debug,
+    // 쿠키 동의 배너를 붙이는 스토어는 "pending"으로 시작하고 배너에서 setConsent를 부른다
+    consent: "granted",
+  };
+  instance = createAnalytics(options);
+  for (const input of pending) instance.track(input);
+  pending = [];
+  return instance;
+}
+
+export function track(input: AnalyticsTrackInput) {
+  if (instance) instance.track(input);
+  else pending.push(input);
+}
+
+/**
+ * 화면이 보일 때 행동을 한 번 남긴다. 내용이 같으면 리렌더·StrictMode 이중 실행에도 다시 보내지
+ * 않는다(SDK도 같은 페이지뷰 안의 중복을 거른다). `null`이면 아무것도 보내지 않는다.
+ */
+export function useTrack(input: AnalyticsTrackInput | null) {
+  const key = input ? JSON.stringify(input) : "";
+  useEffect(() => {
+    if (key) track(JSON.parse(key) as AnalyticsTrackInput);
+  }, [key]);
+}

package/template/app/lib/api.server.ts

@@ -1,4 +1,4 @@
-import { createStorefrontClient } from "@sayren/storefront-sdk";
+import { analyticsIdsFromCookie, createStorefrontClient } from "@sayren/storefront-sdk";
 import { API_BASE_URL, resolveStoreCode } from "./config.server";
 
 /**
@@ -7,6 +7,8 @@ import { API_BASE_URL, resolveStoreCode } from "./config.server";
  * 테넌트는 `X-Store-Code` 헤더로 보낸다. 토큰은 요청마다 넘긴다 — 모듈 전역에 담으면 서버 렌더에서
  * 다른 사용자의 요청에 섞인다.
  *
+ * 방문 분석 쿠키(방문자·세션)를 헤더로 실어 서버가 기록하는 장바구니·결제·구매 이벤트를 방문과 잇는다.
+ *
  * 비회원 장바구니 토큰은 서버가 새로 발급할 수 있다. `onCartToken`으로 받아 쿠키에 다시 심는다.
  */
 export function apiFor(
@@ -23,6 +25,7 @@ export function apiFor(
     accessToken: options.accessToken ?? undefined,
     cartToken: options.cartToken ?? undefined,
     onCartToken: options.onCartToken,
+    ...analyticsIdsFromCookie(request.headers.get("cookie")),
     // 결제 요청에 우리 화면의 origin을 실어 보낸다. 결제 팝업은 이 값으로만 부모 창에
     // 결과를 알린다 — 빠지면 결제는 되지만 주문서가 완료를 못 받는다.
     fetch: (input, init) => {

package/template/app/lib/config.server.ts

@@ -6,6 +6,9 @@ import { storeCodeFromHost } from "./config";
  */
 export const API_BASE_URL = process.env.SAYREN_API_URL ?? "https://api.sayren.app/storefront/v1";
 
+/** localhost에서도 방문 분석을 보낸다 — 기본은 개발 트래픽을 섞지 않으려고 끈다 */
+export const ANALYTICS_DEBUG = process.env.SAYREN_ANALYTICS_DEBUG === "1";
+
 const FIXED_STORE_CODE = process.env.SAYREN_STORE_CODE ?? "";
 
 /** 요청에서 테넌트를 정한다 — 고정 값이 먼저이고, 없으면 호스트 서브도메인에서 뽑는다 */

package/template/app/root.tsx

@@ -1,3 +1,4 @@
+import { useEffect } from "react";
 import {
   isRouteErrorResponse,
   Links,
@@ -8,6 +9,8 @@ import {
 } from "react-router";
 import type { Route } from "./+types/root";
 import { SiteHeader } from "./components/site-header";
+import { type AnalyticsConfig, startAnalytics } from "./lib/analytics";
+import { ANALYTICS_DEBUG, API_BASE_URL, resolveStoreCode } from "./lib/config.server";
 import "./app.css";
 
 export function Layout({ children }: { children: React.ReactNode }) {
@@ -29,7 +32,21 @@ export function Layout({ children }: { children: React.ReactNode }) {
   );
 }
 
-export default function App() {
+export function loader({ request }: Route.LoaderArgs) {
+  const analytics: AnalyticsConfig = {
+    apiBaseUrl: API_BASE_URL,
+    storeCode: resolveStoreCode(request),
+    debug: ANALYTICS_DEBUG,
+  };
+  return { analytics };
+}
+
+export default function App({ loaderData }: Route.ComponentProps) {
+  const { analytics } = loaderData;
+  // 방문 분석은 브라우저에서 한 번 시작한다. 이후 페이지뷰는 SDK가 History API 이동으로 센다
+  useEffect(() => {
+    startAnalytics(analytics);
+  }, [analytics]);
   return <Outlet />;
 }
 

package/template/app/routes/home.tsx

@@ -1,5 +1,6 @@
 import { Link } from "react-router";
 import { ProductCard } from "../components/product-card";
+import { useTrack } from "../lib/analytics";
 import { apiFor } from "../lib/api.server";
 import type { Route } from "./+types/home";
 
@@ -40,19 +41,26 @@ export default function Home({ loaderData }: Route.ComponentProps) {
         </nav>
       ) : null}
 
-      <ProductSection title="추천 상품" products={recommended} />
-      <ProductSection title="새로 들어왔어요" products={latest} />
+      <ProductSection listId="home:recommend" title="추천 상품" products={recommended} />
+      <ProductSection listId="home:latest" title="새로 들어왔어요" products={latest} />
     </div>
   );
 }
 
 function ProductSection({
+  listId,
   title,
   products,
 }: {
+  listId: string;
   title: string;
   products: Awaited<ReturnType<typeof loader>>["recommended"];
 }) {
+  useTrack(
+    products.length
+      ? { name: "product_list_view", listId, productIds: products.map((p) => p.productId) }
+      : null,
+  );
   if (!products.length) return null;
   return (
     <section className="space-y-4">

package/template/app/routes/product-detail.tsx

@@ -1,6 +1,7 @@
 import { useState } from "react";
 import { Form, redirect, useNavigation } from "react-router";
 import { ProductDescription } from "../components/product-description";
+import { useTrack } from "../lib/analytics";
 import { apiFor } from "../lib/api.server";
 import { cartCookie, readCartToken } from "../lib/cart-session.server";
 import { formatPrice } from "../lib/format";
@@ -46,6 +47,7 @@ export async function action({ request, params }: Route.ActionArgs) {
 
 export default function ProductDetail({ loaderData }: Route.ComponentProps) {
   const { product } = loaderData;
+  useTrack({ name: "product_view", productId: product.productId });
   const navigation = useNavigation();
   const submitting = navigation.state !== "idle";
   const hasOptions = product.optionGroups.length > 0;

package/template/app/routes/products.tsx

@@ -1,5 +1,6 @@
 import { Form, Link, useSearchParams } from "react-router";
 import { ProductCard } from "../components/product-card";
+import { useTrack } from "../lib/analytics";
 import { apiFor } from "../lib/api.server";
 import type { Route } from "./+types/products";
 
@@ -28,6 +29,20 @@ export async function loader({ request }: Route.LoaderArgs) {
 export default function Products({ loaderData }: Route.ComponentProps) {
   const { categories, page, applied } = loaderData;
   const [searchParams] = useSearchParams();
+  useTrack(
+    applied.keyword
+      ? { name: "search", query: applied.keyword, resultCount: page.totalElements }
+      : null,
+  );
+  useTrack({
+    name: "product_list_view",
+    listId: applied.keyword
+      ? "search"
+      : applied.categoryId
+        ? `category:${applied.categoryId}`
+        : "all",
+    productIds: page.contents.map((product) => product.productId),
+  });
 
   return (
     <div className="space-y-6">