@sayren/mcp 0.6.0 → 0.8.0

package/dist/index.mjs

@@ -666,10 +666,10 @@ const RULES = [
 	},
 	{
 		id: "loader-first",
-		title: "데이터는 라우트 loader에서 받는다(서버 함수 `createServerFn`)",
-		why: "클라이언트에서 다시 받으면 첫 화면이 비고 검색 노출이 죽는다. SSR을 끄지 않는다",
-		fix: "화면마다 `createFileRoute(...)({ loader })`를 두고 loader가 서버 함수를 부른다. `useEffect`에서 처음 데이터를 받지 않는다",
-		example: "const load = createServerFn().handler(() => apiFor({}).products.list({ size: 20 }));\nexport const Route = createFileRoute(\"/products/\")({ loader: () => load(), component: Products });",
+		title: "데이터는 라우트 loader에서 받는다(서버 함수 `createServerFn`, TanStack Query면 `ensureQueryData`)",
+		why: "클라이언트에서 다시 받으면 첫 화면이 비고 검색 노출이 죽는다. SSR을 끄지 않는다. TanStack Query의 `useQuery`만 쓰면 서버 렌더에는 데이터가 없다",
+		fix: "화면마다 `createFileRoute(...)({ loader })`를 두고 loader가 서버 함수를 부른다. TanStack Query를 쓰면 loader가 `context.queryClient.ensureQueryData(queryOptions)`로 미리 받고 화면은 같은 queryOptions로 `useSuspenseQuery`를 부른다(`setupRouterSsrQueryIntegration`이 캐시를 HTML에 싣는다). `useEffect`에서 처음 데이터를 받지 않는다",
+		example: "const load = createServerFn().handler(() => apiFor().catalog.searchProducts({ size: 24 }));\nconst productsQuery = () => queryOptions({ queryKey: [\"products\"], queryFn: () => load() });\nexport const Route = createFileRoute(\"/products/\")({\n  loader: ({ context }) => context.queryClient.ensureQueryData(productsQuery()),\n  component: Products, // 화면: useSuspenseQuery(productsQuery())\n});",
 		doc: "/guides/mcp-customize",
 		templateFile: "src/routes/products.index.tsx"
 	},
@@ -891,6 +891,8 @@ function verifySources(files) {
 		if (!has("reconsentRequired")) inProject("buyer-reconsent", "재동의가 필요한 구매자를 처리하는 코드가 없다(`reconsentRequired`)");
 	}
 	if (has("createStorefrontClient(") && !has("@sayren/storefront-sdk/analytics")) inProject("analytics-start", "방문 분석을 시작하는 코드가 없다. `@sayren/storefront-sdk/analytics`의 createAnalytics를 브라우저에서 한 번 부른다");
+	const clientQuery = matches(/\buse(Suspense)?Query\(/);
+	if (clientQuery && !has("ensureQueryData(") && !has("prefetchQuery(")) inFile("loader-first", clientQuery, "TanStack Query로 데이터를 받지만 loader에서 `queryClient.ensureQueryData`로 미리 받는 코드가 없다. 서버 렌더에 데이터가 빠진다", /\buse(Suspense)?Query\(/);
 	if (has("createStorefrontClient(") && !has("loader")) inProject("loader-first", "loader에서 데이터를 받는 코드가 없다. 클라이언트 전용으로 그리면 SSR이 죽는다");
 	return findings;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sayren/mcp",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "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.17.0",
+    "@sayren/storefront-sdk": "^0.14.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.17.0",
+    "@sayren/storefront-sdk": "0.14.0",
     "@sayren/ui": "0.1.0"
   }
 }

package/template/README.md

@@ -50,7 +50,34 @@ SAYREN_STORE_CODE=내_스토어_코드
 화면 데이터는 라우트 `loader`가 서버 함수(`createServerFn`)를 불러 받습니다. 첫 요청은 서버에서 그리고, 이후 이동은
 브라우저가 같은 서버 함수를 호출합니다. 담기·결제 요청·로그인 같은 쓰기도 서버 함수라서 토큰이 브라우저 JS에 나가지 않습니다.
 
-헤더와 브라우저 탭 제목은 셀러 콘솔 설정 › 스토어 정보의 스토어 이름·로고(`GET /store`)를 씁니다.
+## 기본 라이브러리
+
+| 라이브러리 | 역할 | 쓰는 곳 |
+| --- | --- | --- |
+| `@tanstack/react-query` · `@tanstack/react-router-ssr-query` | 서버 함수 데이터 캐시. 서버가 채운 캐시를 HTML에 실어 브라우저가 이어 씁니다 | `src/router.tsx`, 상품 목록(`src/lib/catalog-queries.ts`) |
+| `nuqs` | URL 상태(검색어·카테고리·정렬·페이지) | 상품 목록(`src/lib/products-search.ts`) |
+| `react-hook-form` · `@hookform/resolvers` · `zod` | 폼 입력과 검증 | 회원가입 · 주문서 · 비회원 주문 조회(`src/lib/form-schemas.ts`) |
+| `query-string` | 화면 밖(서버 라우트)에서 주소 만들기 | 소셜 로그인 복귀(`src/routes/auth.callback.ts`) |
+
+**데이터(TanStack Query)**: 쿼리는 `queryOptions` 팩토리로 만들고 loader와 화면이 같은 팩토리를 씁니다. loader는
+`context.queryClient.ensureQueryData(productsQuery(search))`로 서버에서 미리 받고, 화면은 `useSuspenseQuery(productsQuery(search))`로
+캐시에서 읽습니다. `queryFn`은 서버 함수를 부릅니다. `useQuery`만 쓰면 서버 렌더에 데이터가 없어 첫 화면이 빕니다.
+주문서(`/checkout`)는 들어올 때마다 주문서를 새로 만들어야 하므로 캐시하지 않고 loader가 서버 함수를 바로 부릅니다.
+
+**URL 상태(nuqs)**: 파서(`productsSearchParams`)가 원천입니다. 라우트 `validateSearch`가 같은 파서로 주소를 읽어 loader에
+넘기고, 화면은 `useQueryStates`로 검색어·정렬을 바꿉니다. 기본값(1페이지·추천순)은 주소에서 빠집니다. 페이지 이동처럼
+자바스크립트 없이도 동작해야 하는 곳은 링크(`<Link search>`)로 둡니다.
+
+**폼(react-hook-form + zod)**: 입력 규칙은 스토어프론트 SDK 스키마(`signupRequestSchema`·`shippingAddressInputSchema`·
+`guestInfoSchema`·`cashReceiptRequestSchema`)를 재사용하고 안내 문구만 붙입니다. 입력 칸은 `src/components/text-field.tsx`를 씁니다.
+브라우저 필수 검사(`required`)는 그대로 두어 빈 칸은 브라우저가 먼저 막습니다. 주문서는 결제창을 클릭 시점에 열어야 하므로
+제출 핸들러에서 같은 스키마로 먼저 동기 검사한 뒤 `payments.prepareWindow()`를 부릅니다(`form.handleSubmit`은 검증을 기다립니다).
+
+**주소 문자열(query-string)**: 화면 안의 URL 상태는 nuqs와 라우터가 맡습니다. 서버 라우트의 `Location` 헤더처럼 라우터 밖에서
+쿼리 문자열을 만들 때만 `queryString.stringifyUrl`을 씁니다.
+
+헤더와 브라우저 탭 제목은 셀러 콘솔 설정 › 스토어 정보의 스토어 이름·로고(`GET /store`)를 씁니다. 탭 제목은
+`{화면} | {스토어 이름}`(예: `회원가입 | 나의첫번째몰`)이고 홈은 스토어 이름만 씁니다. 형식은 `src/lib/page-title.ts` 한 곳에서 바꿉니다.
 
 ## 방문 분석
 
@@ -101,6 +128,7 @@ EU 등 분석 쿠키에 사전 동의가 필요한 지역의 구매자를 받는
   리프레시 토큰의 동시 갱신은 한 번으로 모읍니다. 리프레시 토큰은 한 번 쓰면 폐기되므로 각자 갱신하면 로그아웃됩니다.
   로그아웃은 서버에서 `auth.signOut()`으로 리프레시 토큰을 폐기한 뒤 쿠키를 지웁니다.
 - loader가 서버 함수로 데이터를 받아 그리는 구조 — 컴포넌트에서 다시 받으면 검색 노출과 첫 화면이 죽습니다.
+  TanStack Query를 쓰는 화면도 loader의 `ensureQueryData`를 지우지 않습니다.
 - 결제 도메인 — 셀러 콘솔 설정 › 결제의 **결제 도메인**은 선택형 허용 목록입니다. 비워 두면 https 복귀 주소를 모두 받고,
   등록하면 그 도메인에서만 결제가 됩니다. 등록했다면 이 쇼핑몰을 배포한 주소도 넣습니다. 배포 주소는 PG(토스페이먼츠·포트원)
   가맹 정보에도 등록합니다. 테스트 결제는 localhost에서도 됩니다.
@@ -111,7 +139,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/package.json

@@ -13,12 +13,18 @@
   },
   "dependencies": {
     "@avarlabs/editor": "^0.1.3",
+    "@hookform/resolvers": "^5.9.1",
     "@sayren/storefront-sdk": "workspace:*",
     "@tailwindcss/vite": "^4.3.3",
+    "@tanstack/react-query": "^5.103.1",
     "@tanstack/react-router": "^1.170.38",
+    "@tanstack/react-router-ssr-query": "^1.167.3",
     "@tanstack/react-start": "^1.168.56",
+    "nuqs": "^2.10.1",
+    "query-string": "^9.5.1",
     "react": "^19.3.0",
     "react-dom": "^19.3.0",
+    "react-hook-form": "^7.88.0",
     "tailwindcss": "^4.3.3",
     "zod": "catalog:"
   },

package/template/src/components/fulfillment-codes.tsx

@@ -0,0 +1,110 @@
+import type { FulfillmentReveal, MyOrderItem } from "@sayren/storefront-sdk";
+import { useHydrated } from "@tanstack/react-router";
+import { useState } from "react";
+import type { CodeRevealResult } from "../lib/code-reveal";
+import { formatDateTime } from "../lib/format";
+
+type RevealedCode = FulfillmentReveal["codes"][number];
+
+/**
+ * 코드 발급 상품의 코드 — 가린 값을 보이고 「코드 보기」를 누르면 평문을 받아 이 컴포넌트 상태에만 둔다.
+ * 평문은 주소·스토리지에 남기지 않는다. 코드 발급 상품이 아니거나 받은 코드가 없으면 그리지 않는다.
+ *
+ * `reveal`은 서버 함수를 부르는 호출부 몫이다 — 회원은 액세스 토큰, 비회원은 조회에 쓴 연락처·비밀번호로 확인한다.
+ */
+export function FulfillmentCodes({
+  item,
+  reveal,
+}: {
+  item: MyOrderItem;
+  reveal: () => Promise<CodeRevealResult>;
+}) {
+  const hydrated = useHydrated();
+  const [revealed, setRevealed] = useState<RevealedCode[] | null>(null);
+  const [pending, setPending] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const codes = item.fulfillment?.status === "FULFILLED" ? (item.fulfillment.codes ?? []) : [];
+  if (item.fulfillmentType !== "CODE" || codes.length === 0) return null;
+
+  const open = async () => {
+    setPending(true);
+    setError(null);
+    try {
+      const result = await reveal();
+      if (result.error !== null) setError(result.error);
+      else setRevealed(result.codes);
+    } catch {
+      setError("코드를 불러오지 못했습니다. 잠시 후 다시 시도해 주십시오");
+    } finally {
+      setPending(false);
+    }
+  };
+
+  return (
+    <section aria-label="코드" className="space-y-2 rounded-md bg-chip p-3 text-xs">
+      <p className="font-semibold">코드</p>
+      {revealed ? (
+        <ul className="space-y-1.5">
+          {revealed.map((code) => (
+            <li key={code.codeId} className="flex flex-wrap items-center gap-2">
+              <code className="break-all rounded bg-white px-2 py-1 font-mono text-sm">
+                {code.code}
+              </code>
+              <CopyButton value={code.code} />
+            </li>
+          ))}
+        </ul>
+      ) : (
+        <>
+          <ul className="space-y-1">
+            {codes.map((code) => (
+              <li key={code.codeId} className="flex flex-wrap items-center gap-2">
+                <code className="font-mono text-sm">{code.hint}</code>
+                {code.revealedAt ? (
+                  <span className="text-muted">처음 연 시각 {formatDateTime(code.revealedAt)}</span>
+                ) : null}
+              </li>
+            ))}
+          </ul>
+          <div className="flex flex-wrap items-center gap-3">
+            <button
+              type="button"
+              disabled={!hydrated || pending}
+              onClick={() => void open()}
+              className="h-8 rounded-md bg-ink px-3 font-semibold text-white disabled:opacity-50"
+            >
+              코드 보기
+            </button>
+            <span className="text-muted">코드를 처음 연 시각이 기록됩니다.</span>
+          </div>
+        </>
+      )}
+      {error ? (
+        <p role="alert" className="text-point">
+          {error}
+        </p>
+      ) : null}
+    </section>
+  );
+}
+
+function CopyButton({ value }: { value: string }) {
+  const [copied, setCopied] = useState(false);
+  return (
+    <button
+      type="button"
+      onClick={() => {
+        navigator.clipboard
+          .writeText(value)
+          .then(() => {
+            setCopied(true);
+            setTimeout(() => setCopied(false), 1500);
+          })
+          .catch(() => undefined);
+      }}
+      className="h-7 rounded-md border border-line bg-white px-2 text-xs"
+    >
+      {copied ? "복사함" : "복사"}
+    </button>
+  );
+}

package/template/src/components/fulfillment-downloads.tsx

@@ -0,0 +1,88 @@
+import type { MyOrderItem } from "@sayren/storefront-sdk";
+import { useHydrated } from "@tanstack/react-router";
+import { useState } from "react";
+import { type DownloadResult, formatFileSize } from "../lib/download";
+import { formatDateTime } from "../lib/format";
+
+/**
+ * 파일 다운로드 상품의 파일 — 남은 횟수·기한과 파일마다 「다운로드」 버튼을 보인다. 누르면 서명 주소(수명 300초)를 받아
+ * 브라우저가 바로 그 주소로 간다. 받을 때마다 횟수를 하나 쓴다. 파일 다운로드 상품이 아니거나 제공 전이면 그리지 않는다.
+ *
+ * `download`는 서버 함수를 부르는 호출부 몫이다 — 회원은 액세스 토큰, 비회원은 조회에 쓴 연락처·비밀번호로 확인한다.
+ */
+export function FulfillmentDownloads({
+  item,
+  download,
+}: {
+  item: MyOrderItem;
+  download: (assetId: string) => Promise<DownloadResult>;
+}) {
+  const hydrated = useHydrated();
+  const [pendingAssetId, setPendingAssetId] = useState<string | null>(null);
+  const [remaining, setRemaining] = useState<number | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const info = item.fulfillment?.status === "FULFILLED" ? item.fulfillment.download : null;
+  if (item.fulfillmentType !== "DOWNLOAD" || !info) return null;
+
+  const left = remaining ?? Math.max(info.limit - info.count, 0);
+  const expired = info.expiresAt !== null && new Date(info.expiresAt).getTime() <= Date.now();
+
+  const start = async (assetId: string) => {
+    setPendingAssetId(assetId);
+    setError(null);
+    try {
+      const result = await download(assetId);
+      if (result.error !== null) {
+        setError(result.error);
+        return;
+      }
+      setRemaining(result.remaining);
+      // 서명 주소는 곧 만료된다 — 저장하지 않고 바로 받는다
+      window.location.assign(result.url);
+    } catch {
+      setError("파일을 받지 못했습니다. 잠시 후 다시 시도해 주십시오");
+    } finally {
+      setPendingAssetId(null);
+    }
+  };
+
+  return (
+    <section aria-label="다운로드" className="space-y-2 rounded-md bg-chip p-3 text-xs">
+      <p className="font-semibold">다운로드</p>
+      <p className="text-muted">
+        남은 횟수 {left}/{info.limit}회
+        {info.expiresAt ? ` · 기한 ${formatDateTime(info.expiresAt)}` : ""}
+      </p>
+      {info.files.length === 0 ? (
+        <p className="text-muted">받을 파일이 없습니다.</p>
+      ) : (
+        <ul className="space-y-1.5">
+          {info.files.map((file) => (
+            <li key={file.assetId} className="flex flex-wrap items-center gap-2">
+              <span className="break-all text-sm">{file.fileName}</span>
+              {file.sizeBytes !== null ? (
+                <span className="text-muted">{formatFileSize(file.sizeBytes)}</span>
+              ) : null}
+              <button
+                type="button"
+                aria-label={`${file.fileName} 다운로드`}
+                disabled={!hydrated || pendingAssetId !== null || left <= 0 || expired}
+                onClick={() => void start(file.assetId)}
+                className="ml-auto h-8 rounded-md bg-ink px-3 font-semibold text-white disabled:opacity-50"
+              >
+                다운로드
+              </button>
+            </li>
+          ))}
+        </ul>
+      )}
+      {left <= 0 ? <p className="text-muted">다운로드 횟수를 모두 사용했습니다.</p> : null}
+      {expired && left > 0 ? <p className="text-muted">다운로드 기간이 지났습니다.</p> : null}
+      {error ? (
+        <p role="alert" className="text-point">
+          {error}
+        </p>
+      ) : null}
+    </section>
+  );
+}

package/template/src/components/text-field.tsx

@@ -0,0 +1,71 @@
+import { useId } from "react";
+import type { UseFormRegisterReturn } from "react-hook-form";
+
+/**
+ * react-hook-form 입력 한 칸 — 라벨·필수 표시·안내·검증 오류를 함께 그린다.
+ *
+ * - 이름은 라벨 글자 그대로다(`aria-label`, 필수 표시·안내 문구는 빼고). 안내와 오류는 aria-describedby로 잇는다.
+ * - 프리필은 `defaultValue`로 준다. `register`는 값을 서버 HTML에 싣지 않는다.
+ * - 브라우저 필수 검사(`required`)를 그대로 둔다. 빈 칸은 브라우저가 먼저 막고, 형식은 zod 스키마가 안내한다.
+ */
+export function TextField({
+  label,
+  registration,
+  error,
+  type = "text",
+  defaultValue,
+  autoComplete,
+  placeholder,
+  required,
+  hint,
+}: {
+  label: string;
+  registration: UseFormRegisterReturn;
+  error?: string;
+  type?: string;
+  defaultValue?: string;
+  autoComplete?: string;
+  placeholder?: string;
+  required?: boolean;
+  hint?: string;
+}) {
+  const hintId = useId();
+  const errorId = useId();
+  const describedBy = [hint ? hintId : null, error ? errorId : null].filter(Boolean).join(" ");
+  return (
+    <label className="block space-y-1">
+      <span className="text-sm">
+        {label}
+        {/* 필수 표시는 눈으로만 본다 — 입력의 required가 보조 기술에 필수임을 알린다 */}
+        {required ? (
+          <span aria-hidden="true" className="text-point">
+            {" "}
+            *
+          </span>
+        ) : null}
+      </span>
+      <input
+        {...registration}
+        type={type}
+        defaultValue={defaultValue}
+        autoComplete={autoComplete}
+        placeholder={placeholder}
+        required={required}
+        aria-label={label}
+        aria-invalid={error ? true : undefined}
+        aria-describedby={describedBy || undefined}
+        className={`h-11 w-full rounded-md border px-3 ${error ? "border-point" : "border-line"}`}
+      />
+      {hint ? (
+        <span id={hintId} className="block text-muted text-xs">
+          {hint}
+        </span>
+      ) : null}
+      {error ? (
+        <span id={errorId} className="block text-point text-xs">
+          {error}
+        </span>
+      ) : null}
+    </label>
+  );
+}

package/template/src/lib/catalog-queries.ts

@@ -0,0 +1,47 @@
+import { productSortSchema } from "@sayren/storefront-sdk";
+import { queryOptions } from "@tanstack/react-query";
+import { createServerFn } from "@tanstack/react-start";
+import { z } from "zod";
+import { apiFor } from "./api.server";
+import type { ProductsSearch } from "./products-search";
+
+/**
+ * 카탈로그 쿼리 — TanStack Query의 queryOptions 팩토리다. 라우트 loader(`ensureQueryData`)와 화면
+ * (`useSuspenseQuery`)이 같은 팩토리를 써서 queryKey가 갈라지지 않는다.
+ *
+ * 데이터는 서버 함수로 받는다. 첫 요청은 서버가 받아 HTML에 실어 보내고(SSR 하이드레이션), 이후 이동은 브라우저가
+ * 같은 서버 함수를 부른다. 한 번 받은 조건은 캐시에서 바로 그려 뒤로가기가 빠르다.
+ */
+
+const PRODUCTS_PAGE_SIZE = 24;
+
+const searchProductsInput = z.object({
+  keyword: z.string().optional(),
+  categoryId: z.string().optional(),
+  sort: productSortSchema.optional(),
+  page: z.number().int().min(1).optional(),
+});
+
+const searchProducts = createServerFn({ method: "GET" })
+  .validator(searchProductsInput)
+  .handler(({ data }) =>
+    apiFor().catalog.searchProducts({ ...data, page: data.page ?? 1, size: PRODUCTS_PAGE_SIZE }),
+  );
+
+const listCategories = createServerFn({ method: "GET" }).handler(() =>
+  apiFor().catalog.listCategories(),
+);
+
+/** 카테고리는 자주 바뀌지 않는다 — 화면을 옮겨도 5분 동안 다시 받지 않는다 */
+export const categoriesQuery = () =>
+  queryOptions({
+    queryKey: ["catalog", "categories"],
+    queryFn: () => listCategories(),
+    staleTime: 5 * 60_000,
+  });
+
+export const productsQuery = (search: ProductsSearch) =>
+  queryOptions({
+    queryKey: ["catalog", "products", search],
+    queryFn: () => searchProducts({ data: search }),
+  });

package/template/src/lib/code-reveal.test.ts

@@ -0,0 +1,30 @@
+import { ApiError } from "@sayren/storefront-sdk";
+import { describe, expect, it } from "vitest";
+import { codeRevealErrorMessage, normalizePhone } from "./code-reveal";
+
+describe("codeRevealErrorMessage", () => {
+  it("열람할 코드가 없으면(404) 주문 상태를 확인하게 한다", () => {
+    expect(codeRevealErrorMessage(new ApiError(404, "FULFILLMENT_NOT_FOUND", "x"))).toBe(
+      "열람할 코드가 없습니다. 주문 상태를 확인해 주십시오",
+    );
+  });
+
+  it("시도 한도(429)는 남은 시간을 알린다", () => {
+    const error = new ApiError(429, "TOO_MANY_REQUESTS", "x", undefined, undefined, {
+      retryAfterSeconds: 600,
+    });
+    expect(codeRevealErrorMessage(error)).toContain("10분 뒤");
+  });
+
+  it("그 밖의 실패는 다시 시도하게 한다", () => {
+    expect(codeRevealErrorMessage(new Error("network"))).toBe(
+      "코드를 불러오지 못했습니다. 잠시 후 다시 시도해 주십시오",
+    );
+  });
+});
+
+describe("normalizePhone", () => {
+  it("숫자만 남긴다", () => {
+    expect(normalizePhone("010-1234 5678")).toBe("01012345678");
+  });
+});

package/template/src/lib/code-reveal.ts

@@ -0,0 +1,32 @@
+import { ApiError, type FulfillmentReveal } from "@sayren/storefront-sdk";
+import { guestLookupLockedMessage } from "./guest-order";
+
+/**
+ * 코드 발급 상품의 코드 열람 (sayren 이슈 #48).
+ *
+ * 주문 상세의 코드는 가린 값(`hint`)만 온다. 평문은 구매자가 「코드 보기」를 누를 때 서버 함수가
+ * `myOrders.revealCode`(회원)·`myOrders.revealGuestCode`(비회원)로 받아 그 화면에만 보인다. 평문은
+ * 주소·스토리지·쿠키에 두지 않는다. 처음 연 시각이 기록되고 셀러가 청약철회를 판단하는 근거가 된다.
+ */
+
+/** 서버 함수 결과 — ApiError는 서버 함수 경계를 넘지 못하므로 문구로 바꿔 돌려준다 */
+export type CodeRevealResult =
+  | { codes: FulfillmentReveal["codes"]; error: null }
+  | { codes: null; error: string };
+
+/** 코드 열람 실패 → 구매자에게 보일 문구 */
+export function codeRevealErrorMessage(error: unknown): string {
+  if (error instanceof ApiError) {
+    if (error.status === 404) {
+      return "열람할 코드가 없습니다. 주문 상태를 확인해 주십시오";
+    }
+    // 비회원 열람은 비회원 주문 조회와 같은 시도 한도를 쓴다
+    if (error.status === 429) return guestLookupLockedMessage(error.details?.retryAfterSeconds);
+  }
+  return "코드를 불러오지 못했습니다. 잠시 후 다시 시도해 주십시오";
+}
+
+/** 비회원 열람에 싣는 연락처 — 조회 화면과 같게 숫자만 남긴다 */
+export function normalizePhone(phone: string): string {
+  return phone.replace(/[^0-9]/g, "");
+}

package/template/src/lib/coupon-code.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+import { COUPON_CODE_PATTERN, couponErrorMessage, couponRejectMessage } from "./coupon-code";
+
+describe("쿠폰 코드", () => {
+  it("형식은 영문·숫자·-·_ 6~30자다", () => {
+    expect(COUPON_CODE_PATTERN.test("FALL-10")).toBe(true);
+    expect(COUPON_CODE_PATTERN.test("fall_2026")).toBe(true);
+    expect(COUPON_CODE_PATTERN.test("ABC")).toBe(false);
+    expect(COUPON_CODE_PATTERN.test("가을쿠폰코드")).toBe(false);
+  });
+
+  it("오류 코드와 적용하지 못한 사유를 안내 문구로 바꾸고 모르는 값은 일반 안내다", () => {
+    expect(couponErrorMessage("COUPON_NOT_FOUND")).toContain("찾을 수 없습니다");
+    expect(couponErrorMessage("SOMETHING_NEW")).toContain("적용하지 못했습니다");
+    expect(couponRejectMessage("MIN_ORDER_AMOUNT")).toContain("최소 주문 금액");
+    expect(couponRejectMessage("NEW_REASON")).toBe("이 주문에는 쓸 수 없는 쿠폰입니다.");
+    expect(couponRejectMessage(null)).toBe("이 주문에는 쓸 수 없는 쿠폰입니다.");
+  });
+});

package/template/src/lib/coupon-code.ts

@@ -0,0 +1,60 @@
+import type { CouponResult } from "@sayren/storefront-sdk";
+
+/** 적용한 쿠폰 코드 — 금액 미리보기가 적용을 확인한 값이다. 결제 시작이 같은 코드를 `coupons`로 보낸다 */
+export interface AppliedCoupon {
+  code: string;
+  name: string;
+  discountAmount: number;
+}
+
+/** 쿠폰 코드 형식 — 영문·숫자·`-`·`_` 6~30자. 서버가 다시 검사한다 */
+export const COUPON_CODE_PATTERN = /^[A-Za-z0-9_-]{6,30}$/;
+
+/** 쿠폰 API 오류 코드 → 안내 문구. 모르는 코드는 일반 안내다 */
+export function couponErrorMessage(code: string | null): string {
+  switch (code) {
+    case "COUPON_NOT_FOUND":
+      return "쿠폰 코드를 찾을 수 없습니다. 코드를 다시 확인해 주십시오.";
+    case "TOO_MANY_REQUESTS":
+      return "쿠폰 코드를 너무 여러 번 입력했습니다. 잠시 후 다시 시도해 주십시오.";
+    case "COUPONS_UNAVAILABLE":
+      return "지금은 쿠폰을 쓸 수 없습니다. 쿠폰 없이 결제할 수 있습니다.";
+    case "COUPON_IN_USE":
+      return "다른 결제에서 쓰고 있는 쿠폰입니다. 그 결제가 끝나면 다시 쓸 수 있습니다.";
+    case "COUPON_LIMIT_REACHED":
+      return "이 쿠폰을 쓸 수 있는 횟수를 모두 썼습니다. 진행 중인 결제가 있다면 그 결제가 끝나거나 10분이 지나면 다시 쓸 수 있습니다.";
+    case "COUPON_EXHAUSTED":
+      return "쿠폰이 모두 소진됐습니다. 진행 중인 결제가 있다면 그 결제가 끝나거나 10분이 지나면 다시 쓸 수 있습니다.";
+    case "COUPON_CHANGED":
+      return "쿠폰 조건이 바뀌었습니다. 쿠폰을 다시 적용해 주십시오.";
+    case "PAYMENT_AMOUNT_TOO_LOW":
+      return "쿠폰을 적용하면 결제 금액이 너무 적어 결제할 수 없습니다.";
+    default:
+      return "쿠폰을 적용하지 못했습니다. 잠시 후 다시 시도해 주십시오.";
+  }
+}
+
+/** 적용하지 못한 사유 → 안내 문구. 사유는 늘 수 있어 모르는 값은 일반 안내다 */
+export function couponRejectMessage(reason: CouponResult["rejectReason"]): string {
+  switch (reason) {
+    case "MIN_ORDER_AMOUNT":
+      return "최소 주문 금액에 못 미쳐 쓸 수 없는 쿠폰입니다.";
+    case "NO_ELIGIBLE_ITEMS":
+    case "LINE_NOT_ELIGIBLE":
+      return "주문한 상품에는 쓸 수 없는 쿠폰입니다.";
+    case "MEMBER_ONLY":
+      return "회원 전용 쿠폰입니다. 로그인한 뒤 써 주십시오.";
+    case "NOT_STARTED":
+      return "아직 사용 기간이 아닌 쿠폰입니다.";
+    case "EXPIRED":
+      return "사용 기간이 지난 쿠폰입니다.";
+    case "IN_USE":
+      return "다른 결제에서 쓰고 있는 쿠폰입니다.";
+    case "LIMIT_REACHED":
+      return "이 쿠폰을 쓸 수 있는 횟수를 모두 썼습니다.";
+    case "EXHAUSTED":
+      return "쿠폰이 모두 소진됐습니다.";
+    default:
+      return "이 주문에는 쓸 수 없는 쿠폰입니다.";
+  }
+}

package/template/src/lib/download.test.ts

@@ -0,0 +1,41 @@
+import { ApiError } from "@sayren/storefront-sdk";
+import { describe, expect, it } from "vitest";
+import { downloadErrorMessage, formatFileSize } from "./download";
+
+describe("downloadErrorMessage", () => {
+  it("횟수를 다 썼거나 기간이 지나면 그대로 알린다", () => {
+    expect(downloadErrorMessage(new ApiError(409, "DOWNLOAD_LIMIT_REACHED", "x"))).toBe(
+      "다운로드 횟수를 모두 사용했습니다",
+    );
+    expect(downloadErrorMessage(new ApiError(409, "DOWNLOAD_EXPIRED", "x"))).toBe(
+      "다운로드 기간이 지났습니다",
+    );
+  });
+
+  it("받을 파일이 없으면(404) 주문 상태를 확인하게 한다", () => {
+    expect(downloadErrorMessage(new ApiError(404, "FULFILLMENT_NOT_FOUND", "x"))).toBe(
+      "받을 파일이 없습니다. 주문 상태를 확인해 주십시오",
+    );
+  });
+
+  it("시도 한도(429)는 남은 시간을 알린다", () => {
+    const error = new ApiError(429, "TOO_MANY_REQUESTS", "x", undefined, undefined, {
+      retryAfterSeconds: 600,
+    });
+    expect(downloadErrorMessage(error)).toContain("10분 뒤");
+  });
+
+  it("그 밖의 실패는 다시 시도하게 한다", () => {
+    expect(downloadErrorMessage(new Error("network"))).toBe(
+      "파일을 받지 못했습니다. 잠시 후 다시 시도해 주십시오",
+    );
+  });
+});
+
+describe("formatFileSize", () => {
+  it("1024 단위로 줄이고 모르면 빈 문자열이다", () => {
+    expect(formatFileSize(512)).toBe("512B");
+    expect(formatFileSize(1536)).toBe("1.5KB");
+    expect(formatFileSize(null)).toBe("");
+  });
+});