@sayren/mcp 0.6.0 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sayren/mcp",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "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.15.1",
-    "@sayren/storefront-sdk": "^0.12.0"
+    "@sayren/store-sdk": "^0.16.0",
+    "@sayren/storefront-sdk": "^0.13.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.14",

package/template/.template-meta.json

@@ -8,8 +8,8 @@
   },
   "versions": {
     "@sayren/contracts": "0.1.0",
-    "@sayren/store-sdk": "0.15.1",
-    "@sayren/storefront-sdk": "0.12.0",
+    "@sayren/store-sdk": "0.16.0",
+    "@sayren/storefront-sdk": "0.13.0",
     "@sayren/ui": "0.1.0"
   }
 }

package/template/README.md

@@ -50,7 +50,8 @@ SAYREN_STORE_CODE=내_스토어_코드
 화면 데이터는 라우트 `loader`가 서버 함수(`createServerFn`)를 불러 받습니다. 첫 요청은 서버에서 그리고, 이후 이동은
 브라우저가 같은 서버 함수를 호출합니다. 담기·결제 요청·로그인 같은 쓰기도 서버 함수라서 토큰이 브라우저 JS에 나가지 않습니다.
 
-헤더와 브라우저 탭 제목은 셀러 콘솔 설정 › 스토어 정보의 스토어 이름·로고(`GET /store`)를 씁니다.
+헤더와 브라우저 탭 제목은 셀러 콘솔 설정 › 스토어 정보의 스토어 이름·로고(`GET /store`)를 씁니다. 탭 제목은
+`{화면} | {스토어 이름}`(예: `회원가입 | 나의첫번째몰`)이고 홈은 스토어 이름만 씁니다. 형식은 `src/lib/page-title.ts` 한 곳에서 바꿉니다.
 
 ## 방문 분석
 
@@ -111,7 +112,9 @@ EU 등 분석 쿠키에 사전 동의가 필요한 지역의 구매자를 받는
   매번 다시 계산해야 하기 때문입니다.
 - 비회원 장바구니는 서버가 발급한 토큰으로만 찾습니다. 쿠키를 지우면 담은 상품이 사라집니다.
 - 비회원 주문은 주문번호와 주문서에 적은 연락처·주문 조회 비밀번호로 찾습니다(`/guest-order`). 주문 완료 화면이 주문번호를
-  채워 보냅니다.
+  채워 보냅니다. 주문번호마다 10분에 5번까지 확인하고 5번째가 틀리면 30분 동안(하루 15번을 넘으면 그날 끝까지) `429 TOO_MANY_REQUESTS`라서,
+  화면은 남은 시간(`details.retryAfterSeconds`)을 분 단위로 안내합니다(`src/lib/guest-order.ts`). 주문이 없는 것과
+  연락처·비밀번호가 틀린 것은 같은 `404`입니다.
 - 배송비는 배송 묶음마다 한 번 붙습니다. 같은 출고지 + 같은 배송 정책인 상품이 한 묶음이고, 제주·도서산간 추가
   배송비는 묶음마다 더하며 무료배송이어도 부과합니다. 주문서를 만들 때는 배송지를 몰라 주문서의 `delivery.zipCode`가
   null이고 추가 배송비가 0입니다. 주문서(`/checkout`)는 우편번호 입력을 마칠 때(blur) `quoteDelivery` 서버 함수로

package/template/src/lib/guest-order.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from "vitest";
+import { guestLookupLockedMessage } from "./guest-order";
+
+describe("guestLookupLockedMessage", () => {
+  it("남은 시간을 분 단위로 올려 알린다", () => {
+    expect(guestLookupLockedMessage(1800)).toBe(
+      "조회 시도가 너무 많습니다. 30분 뒤에 다시 시도해 주십시오",
+    );
+    expect(guestLookupLockedMessage(61)).toContain("2분 뒤");
+  });
+
+  it("남은 시간을 모르면 잠시 후로 안내한다", () => {
+    expect(guestLookupLockedMessage(undefined)).toBe(
+      "조회 시도가 너무 많습니다. 잠시 후 다시 시도해 주십시오",
+    );
+    expect(guestLookupLockedMessage("30")).toContain("잠시 후");
+  });
+});

package/template/src/lib/guest-order.ts

@@ -0,0 +1,13 @@
+/**
+ * 비회원 주문 조회 잠금 안내 — API는 주문번호마다 시도 한도를 두고, 넘으면 429 `TOO_MANY_REQUESTS`와
+ * 남은 시간(`details.retryAfterSeconds`)을 준다. 남은 시간은 분 단위로 올려 알린다.
+ */
+export function guestLookupLockedMessage(retryAfterSeconds: unknown): string {
+  const minutes =
+    typeof retryAfterSeconds === "number" && retryAfterSeconds > 0
+      ? Math.ceil(retryAfterSeconds / 60)
+      : null;
+  return minutes
+    ? `조회 시도가 너무 많습니다. ${minutes}분 뒤에 다시 시도해 주십시오`
+    : "조회 시도가 너무 많습니다. 잠시 후 다시 시도해 주십시오";
+}

package/template/src/lib/page-title.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+import { pageTitle } from "./page-title";
+
+const root = { loaderData: { store: { name: "나의첫번째몰", logoUrl: null } } };
+
+describe("pageTitle", () => {
+  it("화면 이름 뒤에 스토어 이름을 붙인다", () => {
+    expect(pageTitle([root, { loaderData: {} }], "회원가입")).toBe("회원가입 | 나의첫번째몰");
+  });
+
+  it("화면 이름이 없으면 스토어 이름만 쓴다", () => {
+    expect(pageTitle([root])).toBe("나의첫번째몰");
+  });
+
+  it("스토어 이름을 읽지 못하면 기본 이름을 쓴다", () => {
+    expect(pageTitle([{ loaderData: { store: null } }], "장바구니")).toBe("장바구니 | 스토어");
+    expect(pageTitle([], "장바구니")).toBe("장바구니 | 스토어");
+  });
+});

package/template/src/lib/page-title.ts

@@ -0,0 +1,23 @@
+/** 스토어 이름을 읽지 못했을 때 탭 제목 */
+export const FALLBACK_STORE_NAME = "스토어";
+
+/** 루트 라우트 loader가 내려 주는 스토어 이름 — `__root.tsx`의 `RootData.store` */
+function storeNameOf(matches: ReadonlyArray<{ loaderData?: unknown }>): string | null {
+  const root = matches[0]?.loaderData as { store?: { name?: unknown } | null } | undefined;
+  const name = root?.store?.name;
+  return typeof name === "string" && name.trim() ? name : null;
+}
+
+/**
+ * 탭 제목 — `{화면} | {스토어 이름}`. 홈처럼 화면 이름이 없으면 스토어 이름만 쓴다.
+ * 라우트 `head`의 `matches`를 그대로 넘긴다(루트 loader가 스토어 이름을 싣는다).
+ *
+ * 확장 지점 — 구분자나 순서를 바꾸려면 여기만 고친다.
+ */
+export function pageTitle(
+  matches: ReadonlyArray<{ loaderData?: unknown }>,
+  screen?: string | null,
+): string {
+  const store = storeNameOf(matches) ?? FALLBACK_STORE_NAME;
+  return screen ? `${screen} | ${store}` : store;
+}

package/template/src/routes/__root.tsx

@@ -13,6 +13,7 @@ import { SiteHeader, type StoreBrand } from "../components/site-header";
 import { type AnalyticsConfig, startAnalytics } from "../lib/analytics";
 import { apiFor } from "../lib/api.server";
 import { ANALYTICS_DEBUG, API_BASE_URL, resolveStoreCode } from "../lib/config.server";
+import { FALLBACK_STORE_NAME } from "../lib/page-title";
 import appCss from "../styles.css?url";
 
 /** 방문 분석 설정 — 서버 값(`process.env`)이라 서버 함수로 내려준다 */
@@ -47,8 +48,9 @@ export const Route = createRootRoute({
     meta: [
       { charSet: "utf-8" },
       { name: "viewport", content: "width=device-width, initial-scale=1" },
-      // 화면마다 제목을 덮어쓴다. 여기 값은 제목을 정하지 않은 화면의 기본값이다
-      { title: loaderData?.store?.name ?? "스토어" },
+      // 화면마다 `{화면} | {스토어 이름}`으로 덮어쓴다(`lib/page-title.ts`). 여기 값은 홈처럼
+      // 화면 이름이 없는 곳의 제목이다
+      { title: loaderData?.store?.name ?? FALLBACK_STORE_NAME },
     ],
     links: [
       { rel: "stylesheet", href: appCss },

package/template/src/routes/account.tsx

@@ -11,6 +11,7 @@ import { z } from "zod";
 import { SubmitButton } from "../components/submit-button";
 import { apiFor, authFor } from "../lib/api.server";
 import { formatDateTime } from "../lib/format";
+import { pageTitle } from "../lib/page-title";
 import { readToken, signOut } from "../lib/session.server";
 import { SOCIAL_BUTTONS } from "../lib/social-buttons";
 import { writeSocialLogin } from "../lib/social-login.server";
@@ -181,7 +182,7 @@ function accountErrorMessage(error: unknown): string {
 export const Route = createFileRoute("/account")({
   validateSearch: accountSearch,
   loader: () => getAccount(),
-  head: () => ({ meta: [{ title: "내 정보" }] }),
+  head: ({ matches }) => ({ meta: [{ title: pageTitle(matches, "내 정보") }] }),
   component: Account,
 });
 

package/template/src/routes/cart.tsx

@@ -7,6 +7,7 @@ import { SubmitButton } from "../components/submit-button";
 import { apiFor } from "../lib/api.server";
 import { readCartToken, writeCartToken } from "../lib/cart-session.server";
 import { formatPrice } from "../lib/format";
+import { pageTitle } from "../lib/page-title";
 import { readToken } from "../lib/session.server";
 
 const getCart = createServerFn({ method: "GET" }).handler(async () => {
@@ -54,7 +55,7 @@ const changeCart = createServerFn({ method: "POST" })
 
 export const Route = createFileRoute("/cart")({
   loader: () => getCart(),
-  head: () => ({ meta: [{ title: "장바구니" }] }),
+  head: ({ matches }) => ({ meta: [{ title: pageTitle(matches, "장바구니") }] }),
   component: CartPage,
 });
 

package/template/src/routes/checkout.complete.tsx

@@ -3,6 +3,7 @@ import { createServerFn } from "@tanstack/react-start";
 import { z } from "zod";
 import { apiFor } from "../lib/api.server";
 import { formatPrice } from "../lib/format";
+import { pageTitle } from "../lib/page-title";
 import { readToken } from "../lib/session.server";
 
 const completeSearch = z.object({ orderId: z.string().optional().catch(undefined) });
@@ -23,7 +24,7 @@ export const Route = createFileRoute("/checkout/complete")({
   validateSearch: completeSearch,
   loaderDeps: ({ search }) => search,
   loader: ({ deps }) => getCompletedOrder({ data: deps }),
-  head: () => ({ meta: [{ title: "주문 완료" }] }),
+  head: ({ matches }) => ({ meta: [{ title: pageTitle(matches, "주문 완료") }] }),
   component: CheckoutComplete,
 });
 

package/template/src/routes/checkout.index.tsx

@@ -21,6 +21,7 @@ import { checkoutIntentFrom, checkoutSearch } from "../lib/checkout-intent";
 import type { PublicConfig } from "../lib/config";
 import { API_BASE_URL, resolveStoreCode } from "../lib/config.server";
 import { formatPrice } from "../lib/format";
+import { pageTitle } from "../lib/page-title";
 import { forgetPaymentOptions, rememberPaymentOptions } from "../lib/payment-options";
 import { PAYMENT_RETURN_PATH, paymentsFor } from "../lib/payments";
 import { readToken } from "../lib/session.server";
@@ -151,7 +152,7 @@ export const Route = createFileRoute("/checkout/")({
   validateSearch: checkoutSearch,
   loaderDeps: ({ search }) => search,
   loader: ({ deps, location }) => createCheckout({ data: { search: deps, back: location.href } }),
-  head: () => ({ meta: [{ title: "주문서" }] }),
+  head: ({ matches }) => ({ meta: [{ title: pageTitle(matches, "주문서") }] }),
   component: Checkout,
 });
 

package/template/src/routes/checkout.return.tsx

@@ -6,6 +6,7 @@ import { useCallback, useEffect, useState } from "react";
 import { z } from "zod";
 import type { PublicConfig } from "../lib/config";
 import { API_BASE_URL, resolveStoreCode } from "../lib/config.server";
+import { pageTitle } from "../lib/page-title";
 import { forgetPaymentOptions, recallPaymentOptions } from "../lib/payment-options";
 import { paymentsFor } from "../lib/payments";
 import { safeRedirect } from "../lib/safe-redirect";
@@ -50,7 +51,12 @@ export const Route = createFileRoute("/checkout/return")({
   validateSearch: returnSearch,
   loader: () => getConfig(),
   // 복귀 주소의 결제 id가 외부 리소스 요청의 Referer로 새지 않게 한다
-  head: () => ({ meta: [{ title: "결제 확인" }, { name: "referrer", content: "no-referrer" }] }),
+  head: ({ matches }) => ({
+    meta: [
+      { title: pageTitle(matches, "결제 확인") },
+      { name: "referrer", content: "no-referrer" },
+    ],
+  }),
   component: PaymentReturn,
 });
 

package/template/src/routes/guest-order.tsx

@@ -7,7 +7,9 @@ import { ProductThumb } from "../components/product-thumb";
 import { SubmitButton } from "../components/submit-button";
 import { apiFor } from "../lib/api.server";
 import { formatDateTime, formatPrice } from "../lib/format";
+import { guestLookupLockedMessage } from "../lib/guest-order";
 import { orderItemStatusLabel } from "../lib/order-status";
+import { pageTitle } from "../lib/page-title";
 
 const guestOrderSearch = z.object({
   /** 주문 완료 화면이 주문번호를 채워 보낸다 */
@@ -36,13 +38,23 @@ const lookupGuestOrder = createServerFn({ method: "POST" })
       if (error instanceof ApiError && (error.status === 401 || error.status === 404)) {
         return { order: null, error: "주문을 찾지 못했습니다. 입력한 내용을 확인해 주십시오" };
       }
+      // 주문번호마다 시도 한도가 있다. 여러 번 틀리면 한동안 맞는 비밀번호로도 조회되지 않는다
+      if (error instanceof ApiError && error.status === 429) {
+        return { order: null, error: guestLookupLockedMessage(error.details?.retryAfterSeconds) };
+      }
       return { order: null, error: "조회하지 못했습니다. 잠시 후 다시 시도해 주십시오" };
     }
   });
 
 export const Route = createFileRoute("/guest-order")({
   validateSearch: guestOrderSearch,
-  head: () => ({ meta: [{ title: "비회원 주문 조회" }] }),
+  head: ({ matches }) => ({
+    // 주소에 주문번호(`?orderId=`)가 실린다. 외부 링크로 나갈 때 리퍼러로 흘리지 않는다
+    meta: [
+      { title: pageTitle(matches, "비회원 주문 조회") },
+      { name: "referrer", content: "no-referrer" },
+    ],
+  }),
   component: GuestOrder,
 });
 

package/template/src/routes/login.tsx

@@ -7,6 +7,7 @@ import { z } from "zod";
 import { SubmitButton } from "../components/submit-button";
 import { apiFor, authFor } from "../lib/api.server";
 import { clearCartToken, readCartToken } from "../lib/cart-session.server";
+import { pageTitle } from "../lib/page-title";
 import { safeRedirect } from "../lib/safe-redirect";
 import { signIn } from "../lib/session.server";
 import { SOCIAL_BUTTONS } from "../lib/social-buttons";
@@ -91,7 +92,7 @@ const CALLBACK_ERRORS: Record<string, string> = {
 export const Route = createFileRoute("/login")({
   validateSearch: loginSearch,
   loader: () => getLoginMethods(),
-  head: () => ({ meta: [{ title: "로그인" }] }),
+  head: ({ matches }) => ({ meta: [{ title: pageTitle(matches, "로그인") }] }),
   component: Login,
 });
 

package/template/src/routes/orders.$orderId.tsx

@@ -16,6 +16,7 @@ import { SubmitButton } from "../components/submit-button";
 import { apiFor } from "../lib/api.server";
 import { formatDateTime, formatPrice } from "../lib/format";
 import { orderItemStatusLabel } from "../lib/order-status";
+import { pageTitle } from "../lib/page-title";
 import { readToken } from "../lib/session.server";
 
 const getOrder = createServerFn({ method: "GET" })
@@ -80,7 +81,9 @@ function claimErrorMessage(error: unknown): string {
 
 export const Route = createFileRoute("/orders/$orderId")({
   loader: ({ params }) => getOrder({ data: { orderId: params.orderId } }),
-  head: ({ params }) => ({ meta: [{ title: `주문 ${params.orderId}` }] }),
+  head: ({ matches, params }) => ({
+    meta: [{ title: pageTitle(matches, `주문 ${params.orderId}`) }],
+  }),
   component: OrderDetail,
 });
 

package/template/src/routes/orders.index.tsx

@@ -2,6 +2,7 @@ import { createFileRoute, Link, redirect } from "@tanstack/react-router";
 import { createServerFn } from "@tanstack/react-start";
 import { apiFor } from "../lib/api.server";
 import { formatDateTime, formatPrice } from "../lib/format";
+import { pageTitle } from "../lib/page-title";
 import { readToken } from "../lib/session.server";
 
 const getOrders = createServerFn({ method: "GET" }).handler(async () => {
@@ -12,7 +13,7 @@ const getOrders = createServerFn({ method: "GET" }).handler(async () => {
 
 export const Route = createFileRoute("/orders/")({
   loader: () => getOrders(),
-  head: () => ({ meta: [{ title: "주문 내역" }] }),
+  head: ({ matches }) => ({ meta: [{ title: pageTitle(matches, "주문 내역") }] }),
   component: Orders,
 });
 

package/template/src/routes/products.$productId.tsx

@@ -10,6 +10,7 @@ import { useTrack } from "../lib/analytics";
 import { apiFor } from "../lib/api.server";
 import { readCartToken, writeCartToken } from "../lib/cart-session.server";
 import { formatPrice } from "../lib/format";
+import { pageTitle } from "../lib/page-title";
 import { readToken } from "../lib/session.server";
 
 const getProduct = createServerFn({ method: "GET" })
@@ -52,7 +53,9 @@ const addToCart = createServerFn({ method: "POST" })
 
 export const Route = createFileRoute("/products/$productId")({
   loader: ({ params }) => getProduct({ data: { productId: params.productId } }),
-  head: ({ loaderData }) => ({ meta: [{ title: loaderData ? loaderData.name : "상품" }] }),
+  head: ({ matches, loaderData }) => ({
+    meta: [{ title: pageTitle(matches, loaderData ? loaderData.name : "상품") }],
+  }),
   component: ProductDetail,
 });
 

package/template/src/routes/products.index.tsx

@@ -4,6 +4,7 @@ import { z } from "zod";
 import { ProductCard } from "../components/product-card";
 import { useTrack } from "../lib/analytics";
 import { apiFor } from "../lib/api.server";
+import { pageTitle } from "../lib/page-title";
 
 /** 목록·검색 조건 — URL에 둔다. 공유·뒤로가기가 그대로 동작한다 */
 const productsSearch = z.object({
@@ -29,7 +30,7 @@ export const Route = createFileRoute("/products/")({
   validateSearch: productsSearch,
   loaderDeps: ({ search }) => search,
   loader: ({ deps }) => searchProducts({ data: deps }),
-  head: () => ({ meta: [{ title: "전체 상품" }] }),
+  head: ({ matches }) => ({ meta: [{ title: pageTitle(matches, "전체 상품") }] }),
   component: Products,
 });
 

package/template/src/routes/signup.tsx

@@ -6,6 +6,7 @@ import { z } from "zod";
 import { SubmitButton } from "../components/submit-button";
 import { apiFor, authFor } from "../lib/api.server";
 import { clearCartToken, readCartToken } from "../lib/cart-session.server";
+import { pageTitle } from "../lib/page-title";
 import { safeRedirect } from "../lib/safe-redirect";
 import { signIn } from "../lib/session.server";
 
@@ -82,7 +83,7 @@ function signupErrorMessage(error: unknown): string {
 export const Route = createFileRoute("/signup")({
   validateSearch: signupSearch,
   loader: () => getSignupAvailable(),
-  head: () => ({ meta: [{ title: "회원가입" }] }),
+  head: ({ matches }) => ({ meta: [{ title: pageTitle(matches, "회원가입") }] }),
   component: Signup,
 });