@zalkera/client 0.6.1

package/llms.txt

@@ -0,0 +1,408 @@
+# zalkera (잘커라) — AI 스토어프론트 빌드 가이드 (llms.txt)
+
+> 이 문서 하나로 잘커라 헤드리스 API 위에 **Next.js 쇼핑몰/예약 스토어프론트**를 만들 수 있다.
+> 관리자 콘솔·백엔드는 잘커라가 제공한다. 당신(AI)이 만들 것은 **공개 사이트(프론트엔드)** 뿐이다.
+> 타입 안전한 클라이언트 `@zalkera/client` 를 통해 백엔드를 호출한다.
+
+## 0. 3줄 요약
+
+1. `@zalkera/client` 의 `createZalkeraClient({ baseUrl, tenant, secretKey? })` 로 클라이언트를 만든다.
+2. **서버 사이드에서만 호출한다**(RSC·route handler·server action). 브라우저에서 직접 부르지 않는다.
+3. 상품 조회는 공개, 장바구니·결제·주문은 고객토큰(로그인) 또는 게스트 세션키/연락처로 식별한다.
+4. `secretKey`(있으면)는 서버 시크릿 — `.env`에만 두고 브라우저에 절대 노출하지 않는다(§2).
+
+## 1. 설치·초기화
+
+```bash
+npm i ./zalkera-client-0.6.0.tgz   # 배포 tarball(심볼릭 링크 말고 tarball — Turbopack 이슈)
+```
+
+```ts
+// lib/zalkera.ts — 서버 전용 싱글턴
+import { createZalkeraClient } from "@zalkera/client";
+
+export const zalkera = createZalkeraClient({
+  baseUrl: process.env.ONEQUE_API_BASE!,        // 예: https://api.zalkera.com (뒤에 /api 붙이지 않는다)
+  tenant: process.env.ONEQUE_TENANT!,           // 이 사이트의 테넌트 코드. 모든 요청에 X-Tenant 로 실린다
+  secretKey: process.env.ONEQUE_STOREFRONT_KEY, // (선택·oqsk_…) 서버 시크릿. 있으면 X-Storefront-Key 로 실린다
+});
+```
+
+- `.env`: `ONEQUE_API_BASE`, `ONEQUE_TENANT`, (선택)`ONEQUE_STOREFRONT_KEY`. **절대 클라이언트 컴포넌트에서 import 하지 말 것** — baseUrl·시크릿 노출.
+- `secretKey`는 진짜 비밀이다 — `NEXT_PUBLIC_*` 접두사·클라이언트 번들 금지. 서버 `.env`에만. 안 주면 종전대로 `tenant`(X-Tenant)만으로 동작(하위호환).
+- 모든 메서드는 성공 시 데이터를, 실패 시 `ZalkeraError`(`.status`, `.code`, `.isRateLimited`, `.isStorefrontKeyError`, `.validationErrors`)를 던진다.
+
+## 2. 왜 서버 사이드인가 (중요)
+
+공개 API 는 `X-Tenant` 헤더를 그대로 믿는다(비인증). 브라우저에서 직접 부르면 baseUrl·CORS 노출.
+그래서 **RSC 또는 route handler(BFF)**에서 호출한다. 장바구니·결제처럼 사용자별 상태가 필요한 호출은
+route handler 를 두고 브라우저 ↔ route handler ↔ 잘커라로 프록시한다(토큰은 httpOnly 쿠키에 보관).
+
+**`secretKey`(스토어프론트 서버 시크릿)** — `X-Tenant` 무인증 신뢰를 키로 승격한 것. 있으면 전
+요청에 `X-Storefront-Key` 로 실려 백엔드가 테넌트 신원을 증명한다(키가 정본). 취급 규칙:
+- 오직 서버 `.env`(`ONEQUE_STOREFRONT_KEY`)에만. `NEXT_PUBLIC_*`·클라이언트 번들 절대 금지 — 이 클라이언트가 서버 전용인 이유.
+- 파트너 콘솔에서 발급(원문 1회 노출·분실 시 회전). 유출 시 콘솔에서 revoke·재발급.
+- 안 주면 종전대로 `tenant`만으로 동작(하위호환). 백엔드가 키를 요구하는 설정이면 키 없이 401 `STOREFRONT_KEY_REQUIRED`.
+
+IP 민감 호출(문의·리드·조회수)은 원 방문자 IP 를 넘겨야 한다:
+```ts
+// route handler 안
+const ip = req.headers.get("x-forwarded-for")?.split(",")[0]?.trim();
+await zalkera.submitInquiry(input, { clientIp: ip });
+```
+
+## 3. API 표면 (전체 메서드)
+
+### 콘텐츠(CMS)
+- `getSiteConfig()` — 회사명·연락처·테마·SEO 기본값
+- `listCategories()` · `listPosts({category?,page?,size?,sort?})` · `getPost(slug)` · `recordPostView(slug,ctx)`
+- `getPage(slug)` · `listMenus()` (HEADER/FOOTER) · `getMediaUrl(id)`
+- `submitInquiry(input, ctx)` · `submitLead(input, ctx)`  ← ctx.clientIp 필수(서버)
+
+### 커머스 — 카탈로그(공개)
+- `listProducts({productType?, keyword?, page?, size?, sort?})` → `Paginated<ProductSummary>` (카드용: slug·name·priceFrom·inStock)
+- `getProduct(slug)` → `ProductDetail { name, productType, variants[] }`
+- `listProductCategories()` → `ProductCategory[]`
+- **variant 가 판매 단위다.** 가격·재고·장바구니·주문은 전부 `variant.id` 기준. 단순 상품도 variant 1개.
+- `variant.inStock`(불리언)·`variant.available`(추적 재고 수량, 무한재고면 null)로 재고 표시.
+- `productType`: `PHYSICAL`(배송)·`DIGITAL`(즉시)·`SERVICE`(예약).
+  **`SERVICE` 는 장바구니·체크아웃을 타지 않는다** — 별도 예약 흐름(§4.6). 담기 시도는 400 이다.
+
+### 커머스 — 상품후기(공개)
+- `listProductReviews(productId, {page?, size?})` → `Paginated<Review>` (공개·VISIBLE 만, **최신순 고정**)
+  - `Review { id, productId, rating(1~5), title, content, photos[], createdAt }`. 작성자 신원은 노출 안 함.
+  - `photos` 는 media asset id 배열 → `getMediaUrl(id)` 로 URL 화.
+- `getProductReviewSummary(productId)` → `RatingSummary { productId, reviewCount, averageRating }` (후기 없으면 0·0)
+- `createProductReview(productId, {orderItemId, rating(1~5), title?, content, photos?}, accessToken)` → `Review`
+  **로그인 필수 + 구매검증**: orderItemId 는 **주문 상세(getOrder)의 items[].id** 에서 얻는다(다른 데선 못 얻음).
+  서버가 본인 주문·배송완료(DELIVERED)·상품 일치 3중 확인. 라인당 1개(재작성 409).
+  - 목록 카드의 별점 배지처럼 값싸게 쓴다(product 비정규화 집계에서 읽음).
+- **후기는 상품의 숫자 `id`(productId)로 조회한다 — slug 가 아니다.** `getProduct(slug)` → `ProductDetail.id`
+  로 획득한다(0.4.0 에서 ProductDetail 에 id 노출). 즉 상품 상세에서 `const p = await getProduct(slug);
+  const reviews = await listProductReviews(p.id);` 로 곧바로 붙인다. **후기 데이터는 하드코딩하지 않는다.**
+
+### 예약 (SERVICE 상품 — 카트 안 탐)
+- `availability({productId, from, to}, options?)` → `AvailabilitySlot[]` (**공개**·비로그인 가능)
+  - `{ slotId, resourceId, startAt, endAt, availableCount }`. 미래·잔여정원 있는 OPEN 슬롯만.
+  - **가용 판정은 `availableCount`** — 카탈로그의 `inStock`/`available` 아님(슬롯마다 정원이 따로).
+- `createBooking(accessToken, { slotId, quantity?, contactName?, contactPhone? })` → `Booking` (**로그인 필수**)
+  - `Booking { bookingCode, productId, slotId, startAt, endAt, quantity, status, orderNo, createdAt }`
+  - **`orderNo` 가 분기다**: 유료·예약금이면 `status=PENDING` + orderNo → `startPayment(orderNo)` 로
+    기존 결제 흐름(§4.3). 무료면 orderNo=null·즉시 `CONFIRMED`.
+- `myBookings(accessToken)` · `cancelBooking(accessToken, bookingCode)` ·
+  `rescheduleBooking(accessToken, bookingCode, newSlotId)` — 전부 **bookingCode** 로(숫자 id 아님).
+
+### 커머스 — 고객 인증(소셜)
+- `socialLogin({ provider, code, redirectUri? })` → `AuthTokens { accessToken, refreshToken, customer }`
+  - provider: `KAKAO`|`NAVER`|`GOOGLE`. 소셜 리다이렉트로 받은 `code` 를 넘기면 백엔드가 교환.
+- `refreshSession(refreshToken)` → 새 토큰(회전). `logout(accessToken)`. `getMe(accessToken)`.
+- `getConsents(accessToken)` → `ConsentStatus[]` · `updateConsents(accessToken, consents)` → 확인 메시지 (마케팅 수신 토글 등·append).
+- **accessToken 은 15분**, refreshToken 은 매 교환마다 회전. 둘 다 httpOnly 쿠키에 저장 권장.
+
+### 커머스 — 장바구니 (session = { accessToken? , cartSessionKey? })
+- `getCart(session)` · `addToCart(variantId, qty, session)` · `updateCartItem(variantId, qty, session)`
+  · `removeFromCart(variantId, session)` · `clearCart(session)`
+- 로그인 고객은 `accessToken`, **게스트는 `cartSessionKey`**(브라우저가 만든 안정적 랜덤 문자열, 쿠키 보관).
+- 카트는 가격을 동결하지 않는다 — 조회할 때마다 현재가. 재고도 잠그지 않는다.
+
+### 커머스 — 결제·주문·배송
+- `checkout(input, session)` → `OrderDetail`  (input: `{ buyerName, buyerPhone, buyerEmail?, shipTo? }`)
+  - 주문 생성 시 가격 스냅샷 동결 + 재고 원자적 차감. 재고 부족이면 409. 상태 `PENDING_PAYMENT`.
+- `startPayment(orderNo, access)` → `{ paymentUrl }` — 고객을 paymentUrl 로 리다이렉트.
+- `getOrder(orderNo, access)` · `listMyOrders(accessToken,{page,size})` · `cancelOrder(orderNo, access)`
+  · `completeOrder(orderNo, access)` · `getShipment(orderNo, access)`
+- `access = { accessToken? }`(로그인) **또는 `{ phone? }`(게스트, 주문 시 남긴 연락처)**.
+
+## 4. 레시피
+
+### 4.1 상품 목록 페이지 (RSC)
+```tsx
+// app/products/page.tsx
+import { zalkera } from "@/lib/zalkera";
+export default async function Products() {
+  const categories = await zalkera.listProductCategories();
+  // 카테고리별 상품 목록은 카테고리 페이지에서. 여기선 카테고리 내비 + (별도) 상품 카드.
+  return <nav>{categories.map(c => <a key={c.id} href={`/c/${c.slug}`}>{c.name}</a>)}</nav>;
+}
+```
+
+### 4.2 상품 상세 + 장바구니 담기
+```tsx
+// app/products/[slug]/page.tsx (RSC) — 조회는 공개
+const product = await zalkera.getProduct(params.slug);
+// 클라이언트 컴포넌트에서 variant 선택 → route handler 로 담기 POST
+```
+```ts
+// app/api/cart/add/route.ts (BFF)
+export async function POST(req: Request) {
+  const { variantId, quantity } = await req.json();
+  const session = { accessToken: cookieAccessToken(), cartSessionKey: ensureCartCookie() };
+  const cart = await zalkera.addToCart(variantId, quantity, session);
+  return Response.json(cart);
+}
+```
+- `ensureCartCookie()`: 게스트면 랜덤 키를 만들어 httpOnly 쿠키에 저장하고 그 값을 쓴다.
+
+### 4.3 결제 플로우 (게스트/로그인 공통)
+1. 카트 확인 → `checkout({ buyerName, buyerPhone, shipTo }, session, idempotencyKey)` → `order.orderNo`.
+2. `startPayment(order.orderNo, access)` → **벤더에 따라 두 갈래**(테넌트가 자기 PG 를 고른다 — 기본 TOSS):
+   ```ts
+   const session = await zalkera.startPayment(orderNo, access);
+   if (session.widget) {
+     // 위젯형(토스) — 내 사이트에서 결제창을 띄우고, 성공 콜백 파라미터를 confirm 으로 넘긴다
+     //   widget = { vendor:"TOSS_PAYMENTS", clientKey, orderId, amount, orderName }
+     //   → 스타터의 checkout/page.tsx(openWidget)·payment/complete/page.tsx 를 그대로 쓴다
+     await zalkera.confirmPayment(orderNo, { paymentKey }, access);   // BFF 경유
+   } else {
+     redirect(session.paymentUrl);   // 리다이렉트형(PayOneQ 등)
+   }
+   ```
+   `widget` 유무로만 분기한다 — **벤더 이름으로 분기하지 마라**(벤더가 늘어난다).
+3. 페이원큐 결제창에서 결제. **결과는 서버 웹훅으로 백엔드가 처리**(프론트는 관여 안 함).
+4. returnUrl 로 돌아오면 `getOrder(orderNo, access)` 로 상태 확인(잠시 PENDING 일 수 있음 → PAID 폴링/새로고침).
+
+> ⚠️ returnUrl·successUrl 콜백의 "성공"을 **신뢰하지 말 것**. 진짜 확정은 백엔드가 한다 — 웹훅(리다이렉트형)
+> 또는 confirm(위젯형: 서버가 **저장된 주문 금액**으로 PG 에 직접 묻는다). 콜백의 `amount` 를 넘겨도 서버는
+> 안 믿으니 브라우저에서 금액을 조작해도 승인되지 않는다. 프론트는 화면 전환만, 상태는 항상 `getOrder`.
+> `confirmPayment` 는 **재호출이 안전**하다(이미 승인된 주문은 조용히 통과 — 웹훅이 먼저 와도 멱등).
+
+> **멱등키(권장)** — `checkout` 3번째 인자. 같은 키·같은 입력의 재요청은 새 주문을 만들지 않고 **원주문을
+> 그대로 반환**한다(더블클릭·네트워크 재시도 안전). 같은 키·다른 입력은 409.
+> **키의 수명 = "주문 시도 1묶음"(성공이 브라우저에 도달할 때까지). 새 주문은 새 키다.** 호출마다 새로
+> 만들면 재시도가 서로 다른 키를 들고 가 아무것도 못 막고, 반대로 **키를 영구 재사용하면 그 브라우저는
+> 두 번째 주문을 영영 못 한다**(같은 키·다른 입력 → 409). SDK 가 자동 생성하지 않는 이유가 이것이다 —
+> 이 수명을 아는 건 앱뿐이다.
+>
+> 관용구는 소비자에 따라 둘이다:
+> - **브라우저(쿠키 있음)** = `` `co-${session.cartSessionKey}` `` **+ 체크아웃 성공 응답에서 카트 쿠키 회전**
+>   (스타터 `rotateCartSessionKey`). **회전 없이 카트키를 멱등키로 쓰지 마라** — 카트 쿠키는 30일이라
+>   회전이 없으면 위의 "영구 재사용"이 그대로 실현된다(실측 사고). 회전을 응답에 실으면 Set-Cookie 가
+>   성공 도달과 원자적으로 묶여서, 응답 유실 시엔 옛 키가 살아남아 재시도가 원주문을 재생한다 —
+>   **인메모리 "시도당 키"보다 이 쪽이 안전하다**(새로고침에 안 죽는다).
+> - **AI 구매 에이전트(쿠키 없음)** = 시도당 UUID 를 스스로 만들어 **성공·확정까지 보관**하고 재시도에 재사용.
+>
+> 생략하면 종전 동작(중복 제출은 카트가 이미 소비돼 404 `CART_NOT_FOUND`).
+> 충돌은 `e.code === "IDEMPOTENCY_CONFLICT"` 로 **프로그램적으로 감지**한다(§6).
+
+### 4.4 게스트 주문 조회 (비회원 배송조회)
+```ts
+// 주문번호 + 연락처로 조회 — 로그인 불필요
+const order = await zalkera.getOrder(orderNo, { phone });
+const shipment = await zalkera.getShipment(orderNo, { phone }); // 배송 상태·추적 이벤트
+```
+
+### 4.5 소셜 로그인 (카카오 예시)
+1. 프론트에서 카카오 인가 URL 로 보냄 → 카카오가 `code` 로 redirect.
+2. 콜백 route handler 에서 `zalkera.socialLogin({ provider:"KAKAO", code, redirectUri })`.
+3. 받은 `accessToken`·`refreshToken` 을 httpOnly 쿠키에 저장. 이후 shop 호출에 `accessToken` 사용.
+4. 만료(401)면 `refreshSession(refreshToken)` 으로 회전 후 재시도.
+
+### 4.6 예약 서비스(SERVICE 상품) — **카트를 타지 않는다**
+
+> ⚠️ **`SERVICE` 상품은 장바구니에 담기지 않는다**(`addToCart` → 400). 예약은 슬롯을 잡는 일이라
+> 카트에 실으면 체크아웃이 오염된다(혼합주문). **별도 흐름**을 탄다.
+> (이 문단은 예전에 "같은 카트·주문 흐름을 탄다"고 적혀 있었다 — 예약 엔진이 붙기 전 이야기였고,
+> 지금은 틀렸다. 그 말을 믿고 만든 담기 버튼은 400 으로 죽는다.)
+
+**상품 상세에서 `productType === "SERVICE"` 면 담기 버튼 대신 슬롯 선택을 그린다.**
+
+```tsx
+// 1) 슬롯 보여주기 — 공개(비로그인 가능).
+// ⚠️ 이 RSC 직독 샘플은 **요청마다 렌더되는 동적 라우트에서만** 신선하다. 상품 상세가 ISR
+//    (force-static + revalidate=N)이면 슬롯이 프리렌더에 구워져 N초 낡은 시간표를 보여주고
+//    SLOT_FULL 을 만든다 — 그땐 **클라이언트 아일랜드 + BFF 프록시**로 내려라(스타터
+//    BookingPanel + /api/booking/availability 가 그 선례다. 볼라틸한 데이터는 클라이언트 아일랜드로).
+const slots = await zalkera.availability({
+  productId: product.id,               // slug 아님 — getProduct(slug).id
+  from: new Date().toISOString(),
+  to: new Date(Date.now() + 14 * 864e5).toISOString(),
+});
+// 가용 판정은 slot.availableCount — 카탈로그의 inStock/available 이 아니다(슬롯마다 정원이 따로).
+```
+
+```ts
+// 2) 예약 잡기 — 로그인 필수(게스트 예약 없음). BFF route handler 에서.
+const booking = await zalkera.createBooking(accessToken, { slotId, quantity: 1 });
+
+// 3) 유료·예약금이면 결제로 — 예약 전용 결제 API 는 없다. 기존 흐름을 그대로 탄다.
+if (booking.orderNo) {                  // status=PENDING
+  const payment = await zalkera.startPayment(booking.orderNo, { accessToken });
+  // 이후는 §4.3 과 완전히 동일(widget 유무로 분기).
+}
+// 무료 예약이면 orderNo=null 이고 이미 CONFIRMED — 결제 단계가 없다.
+```
+
+- 그 외: `myBookings(accessToken)` · `cancelBooking(accessToken, code)`(시작 전·무료만) ·
+  `rescheduleBooking(accessToken, code, newSlotId)`(같은 상품의 다른 슬롯).
+- **취소·변경은 `bookingCode`** 로 한다(숫자 id 아님).
+- **errorCode**(전부 실코드 — 의미까지 실측한 것만 적었다):
+  - 생성: `SLOT_FULL`(**정원 부족·마감·과거 슬롯 전부 이것** — 원자 소비 실패라 한 코드로 뭉친다.
+    목록이 stale 하니 `availability` 재조회 후 다시 보여줘라) · `SLOT_NOT_FOUND`(404) ·
+    `QUANTITY_EXCEEDED`(**1회 예약 수량 한도(10) 초과 또는 1 미만** — 잔여 부족이 아니다. 잔여
+    부족은 `SLOT_FULL` 이다).
+  - 취소: `PAID_CANCEL_ADMIN_ONLY`(**유료 예약은 고객이 못 취소한다 — 매장 문의 안내를 띄워라**) ·
+    `CANCEL_AFTER_START`(이미 시작함) · `INVALID_BOOKING_STATE`(이미 종단) · `BOOKING_NOT_FOUND`.
+  - 변경: `SLOT_PRODUCT_MISMATCH`(다른 상품의 슬롯으로는 못 옮긴다) · `SLOT_FULL` ·
+    `SLOT_NOT_FOUND` · `CANCEL_AFTER_START` · `INVALID_BOOKING_STATE` · `BOOKING_NOT_FOUND`.
+  - 공통: `CUSTOMER_INACTIVE`(로그인 4액션 전부 — 계정 비활성) · 미로그인 401.
+  - ⚠️ **남의 예약도 `BOOKING_NOT_FOUND`(404)** 다 — 서버가 존재를 감춘다(403 아님). "권한 없음"
+    코드는 없으니 찾지 마라.
+
+### 4.7 광고 랜딩 리드 폼 (`submitLead`)
+
+- **문의(§4.6 아님·`submitInquiry`)와 다른 점**: 연락처(phone)가 필수·이메일이 선택이고, 광고 유입
+  추적(UTM·클릭ID)을 `tracking` 으로 동봉한다. 반환은 `{id}`, 레이트리밋 30건/60초(테넌트×IP).
+- **쿼리 → `LeadTracking` 매핑 8종**: `utm_source/medium/campaign/adgroup/content` → `utmSource/…`,
+  `fbclid`·`gclid`·`nclid` 동명. **UTM 은 클라이언트 아일랜드가 mount 후 `window.location.search`
+  로 캡처**한다 — 랜딩이 ISR(force-static)이면 RSC `searchParams`·`useSearchParams()` 는 정적 셸을
+  깨므로 금지(하나라도 있으면 `tracking` 을 채우고, 전무면 undefined).
+- **BFF 필수**: 브라우저에서 `submitLead` 직호출 금지(§2). route handler 에서 `x-forwarded-for` 첫
+  홉을 `{ clientIp }` 로 넘긴다(안 넘기면 방문자 전원 429 — §4.6·문의와 동일 관용구).
+- 선례: `components/LeadForm.tsx`(아일랜드·UTM 캡처) · `app/api/lead/route.ts`(BFF·201 관통).
+
+## 5. 흔한 실수(하지 말 것)
+
+- ❌ 클라이언트 컴포넌트에서 `@zalkera/client` import → baseUrl 노출. ✅ 서버에서만.
+- ❌ variant 없이 product.id 로 장바구니 담기. ✅ 항상 `variant.id`.
+- ❌ **예약(SERVICE) 상품에 담기 버튼**. ✅ `productType === "SERVICE"` 면 슬롯 선택(§4.6) — 담기는 400 이다. 예약 CTA 는 상품 상세로 보내는데 거기 담기밖에 없으면 고객이 죽는 경로가 된다.
+- ❌ 게스트 카트에 cartSessionKey 안 넘김 → 매 요청 새 카트. ✅ 쿠키로 안정적 키 유지.
+- ❌ 카트키를 멱등키로 쓰면서 체크아웃 성공 시 **회전을 안 함** → 그 게스트는 30일간 재주문 불가(409).
+  ✅ 성공 응답에서 카트 쿠키 회전(`rotateCartSessionKey`) — 회전과 카트키 멱등은 한 세트다.
+- ❌ returnUrl "결제성공"을 믿고 주문완료 처리. ✅ `getOrder` 로 상태 확인(웹훅이 정본).
+- ❌ 재고를 `variant.available` 숫자로만 판단. ✅ 무한재고(null)는 `inStock` 으로.
+- ❌ **인라인 `style={{}}` 로 화면 구성**. ✅ Tailwind 유틸리티 클래스로만 스타일한다(§8). 인라인 style 은
+  CSS 변수 주입(`style={{"--...": ...}}`)에만 허용된다.
+- ❌ **`var(--oneq-*)` 참조**(정의처 없는 죽은 레거시 토큰). ✅ 테넌트 색은 토큰 유틸리티(`bg-primary`·
+  `text-primary` 등, §8)로 쓴다.
+- ❌ 서버에서 `submitInquiry`/`submitLead`/`recordPostView` 부를 때 clientIp 누락 → 방문자 전원 rate-limit.
+- ❌ **상품·후기·게시글 등 도메인 데이터를 하드코딩**(리터럴 배열·목업 후기 등). ✅ 반드시 `@zalkera/client`
+  로 조회한다. 계약에 없는 데이터(예: slug→productId 매핑이 없어 후기를 못 붙임)면 **하드코딩으로 때우지
+  말고 그 사실을 보고**한다. 하드코딩한 데이터는 프리뷰·실사이트에서 실데이터와 갈라져 첫인상을 죽인다.
+- ❌ **읽기 페이지를 요청마다 서버 렌더(SSR)**. ✅ SEO 페이지(홈·목록·상세·콘텐츠)는 **ISR**
+  (`export const revalidate = N`) 또는 static 으로 둔다 — page 레벨에서 `cookies()`/`headers()`/
+  `export const dynamic='force-dynamic'`/`fetch(...,{cache:'no-store'})` **금지**(per-page SSR 유발).
+  실시간·개인화 데이터(라이브 재고·개인화)는 **클라이언트 컴포넌트(아일랜드)**로 가져오고, 상태 변경
+  (장바구니·주문)은 **BFF route handler** 로 한다. 신선도는 **온디맨드 revalidate**(백엔드 데이터 변경 시
+  `POST /api/revalidate`)로 지킨다. 동적 SSR 이 꼭 필요하면(예: 검색) **정당화 주석**(`// oneque-allow-dynamic:
+  <이유>`)이 필요하다 — 서버 동적 렌더는 상시 런타임 원가라 CI validator(§5)가 SEO 라우트에서 강제 차단한다.
+
+## 5.1 산출물 규범 — 발견되는 사이트 (필수)
+
+만드는 사이트는 **사람이 보는 UI**와 **검색·AI 가 읽는 구조**를 동시에 만족해야 한다. 아래는 선택이 아니다.
+독립 브랜드 사이트가 발견되는 경로는 검색 리치결과·AI 답변(ChatGPT 등)이고, 그 입장권이 이것들이다.
+
+- ✅ **SEO 페이지에 JSON-LD(schema.org) 필수.** 상품 상세 = `Product` + variant 마다 `Offer`(price·
+  priceCurrency·availability) + 후기 있으면 `AggregateRating`. 홈 = `Organization`(오프라인 점포면
+  `LocalBusiness`, 뷰티샵이면 `BeautySalon` 으로 좁힌다). 목록·상세엔 `BreadcrumbList`.
+  스타터의 `src/components/JsonLd.tsx`(안전 직렬화 + `productJsonLd`/`organizationJsonLd`/
+  `breadcrumbJsonLd` 헬퍼)를 **그대로 쓴다 — 재발명 금지**.
+- ✅ **`sitemap.ts`·`robots.ts` 필수.** sitemap 엔 **실제로 존재하는 공개 라우트만**(홈·상품 상세·콘텐츠).
+  robots 는 세션·쓰기 경로(`/api/`·`/cart`·`/checkout`·`/mypage`·`/orders`·`/login`·`/auth`)만 막고
+  공개 카탈로그는 전부 연다. **AI 크롤러(GPTBot·ClaudeBot 등)를 막지 마라** — 발견 경로를 우리 손으로 닫는 것이다.
+- ✅ **절대 URL.** JSON-LD·sitemap·robots 는 상대경로 불가. 단일 사이트는 env(`ONEQUE_SITE_URL`),
+  멀티테넌트는 요청 호스트에서 만든다.
+- ✅ **ISR 유지.** JSON-LD 를 넣는다고 페이지를 동적으로 만들지 마라 — 전부 프리렌더 값이다(§5 ISR-우선과 한 몸).
+  `sitemap.ts`/`robots.ts` 는 page 가 아니라 크롤러 엔드포인트라 호스트 기반 동적이 정당한 예외다.
+- ❌ **페이지에 없는 것을 JSON-LD 에 쓰지 마라.** 구조화 데이터는 **보이는 내용만** 서술한다. 후기 0건인데
+  `aggregateRating`, 렌더하지도 않는 `image`, 지어낸 브랜드·재고는 전부 구조화 데이터 정책 위반(리치결과 박탈).
+  값이 없으면 **그 필드를 통째로 뺀다**(널·0 을 넣지 않는다).
+- ✅ **상품 이미지는 `/media/{id}` 안정 URL 로.** 스타터의 `src/app/media/[id]/route.ts` 가 `X-Tenant` 를 붙여
+  백엔드를 부르고 302 Location 만 넘긴다(바이트는 스토리지→브라우저 직행 — Next 런타임에 태우지 마라).
+  `<img src={`/media/${product.coverAssetId}`} loading="lazy">` + JSON-LD `image` 둘 다 이 URL 을 쓴다.
+  `next/image` 는 최적화 프록시가 바이트를 런타임에 태우므로 금지(쓰려면 `unoptimized`).
+- ❌ **`getMediaUrl` 의 presigned URL 을 마크업·JSON-LD 에 직접 쓰지 마라.** 수 분 뒤 죽는다 — ISR 로 캐시된
+  HTML 안에서(상세 revalidate 300s) 서명이 먼저 만료돼 이미지가 깨지고, 크롤러가 캐시하면 JSON-LD 도 죽는다.
+
+- ❌ 배송 전(PAID)에 후기 작성 시도 → `NOT_DELIVERED_YET`(409). ✅ 주문이 **DELIVERED 이상**일 때만
+  버튼을 낸다(상태로 게이트). orderItemId 는 주문 상세 items[].id 에서만 얻는다 — 상품 상세엔 없다.
+
+## 6. 에러 처리
+
+**원인 분기는 `e.code`(기계 판독 `errorCode`)로 한다.** 한 엔드포인트가 같은 상태코드로 여러 원인을 낸다 —
+checkout 의 409만 해도 재고부족·판매불가·멱등충돌이고 **처방이 전부 다르다**. `e.message` 는 사람용
+한국어라 **문자열 매칭 금지**(문구가 바뀌면 분기가 깨진다).
+
+```ts
+import { ZalkeraError } from "@zalkera/client";
+try { await zalkera.checkout(input, session, idempotencyKey); }
+catch (e) {
+  if (e instanceof ZalkeraError) {
+    if (e.code === "OUT_OF_STOCK") /* 수량 줄이기 안내 — 카트 재조회로 현재 재고 표시 */;
+    if (e.code === "ITEM_NOT_PURCHASABLE") /* 판매중지된 품목 제거 안내 */;
+    if (e.code === "IDEMPOTENCY_CONFLICT") /* 같은 키로 다른 주문 — 키 수명 버그(§4.3). 1순위 용의자:
+                                              카트키를 멱등키로 쓰면서 성공 시 회전을 안 함 */;
+    if (e.code === "CART_NOT_FOUND") /* 카트 만료/이미 주문됨 — 주문내역 확인 유도 */;
+    if (e.isRateLimited) /* 429 */;
+    if (e.isStorefrontKeyError) /* secretKey 오배선 — 서버 설정 점검(방문자 노출 X). 아래 참고 */;
+    if (e.validationErrors.length) /* 400 필드 검증 — 필드별 메시지 노출 */;
+  }
+}
+```
+
+- **스토어프론트 키 오배선은 개발자 신호다**(방문자에게 노출 금지): `e.isStorefrontKeyError` 로 묶어 잡는다.
+  - `STOREFRONT_KEY_REQUIRED`(401) — 백엔드 `required` 인데 키 없음/무효 → `secretKey` 옵션 설정(콘솔 발급→서버 `.env`).
+  - `TENANT_MISMATCH`(403) — `secretKey` 가 `tenant` 와 다른 테넌트의 키 → 두 값 정합 확인.
+  - 이 두 코드는 SDK 가 안내 메시지를 매핑해 둔다(`e.message` 그대로 로그에 유용).
+- `e.code` = 백엔드 `ErrorCode` enum 이름. 엔드포인트별 발생 코드 목록의 정본은 **OpenAPI**다.
+- 코드 이름은 **전역 유일이 아니다**(ORDER_NOT_FOUND 가 여러 도메인에 있다) — 분기는 그 엔드포인트 문맥에서.
+- 코드를 안 싣는 구버전 백엔드에서는 `e.code` 가 HTTP 사유구("Conflict")로 **폴백**한다. 폴백 값에
+  의존하는 분기를 짜지 마라.
+
+## 7. 결제 파트너
+
+결제·정산은 **페이원큐(PayOneQ)** 가 실행한다. 프론트는 카드정보를 절대 다루지 않는다(PCI 범위 밖).
+`startPayment` 가 준 URL 로 보내고, 결과는 백엔드가 웹훅으로 받아 주문 상태를 바꾼다.
+
+## 8. 스타일 규약 — Tailwind v4 + 테마 토큰 (필수)
+
+스타터(템플릿)는 **Tailwind v4** 와 **테마 토큰**으로 스타일한다. 화면을 그릴 때 아래를 지킨다 — 어기면
+생성물이 초라해지거나(생짜 HTML) 테넌트의 "말로 색 바꾸기"가 깨진다. CI validator(S1~S5)가 강제한다.
+
+**스택 — 이것만 쓴다**
+- ✅ **Tailwind v4 유틸리티 클래스로만** 스타일한다. CSS 파일은 `src/app/globals.css` **하나뿐**이다 —
+  새 `.css` 파일·CSS Modules·CSS-in-JS 를 추가하지 마라(S3·S5).
+- ❌ 인라인 `style={{}}`(S2), 웹폰트·외부 스타일 CDN 추가, `tailwind.config.*` 생성(v4 는 config 없이 돈다).
+  인라인 style 은 **CSS 변수 주입**(`style={{"--x":v}}`) 한 용례에만 허용된다(루트 layout 의 테마 주입이 그것).
+
+**토큰 — 색은 토큰으로만**
+| 유틸리티 | 뜻 |
+|---|---|
+| `bg-primary` `text-primary` `border-primary` | 테넌트 액센트(브랜드색). CTA·가격·강조에만 |
+| `text-primary-foreground` | primary 배경 위 글자(대비 자동 산출) |
+| `bg-background` `text-foreground` | 페이지 배경·본문 글자 |
+| `text-muted` | 보조 텍스트(설명·메타) |
+| `border-border` | 경계선 | `bg-surface` | 카드·필드 배경 | `text-danger` | 오류 |
+
+- ✅ 테넌트 브랜드색은 **`primary` 토큰으로만** 표현한다. ❌ hex 하드코딩(`bg-[#e91e63]`)은 콘솔의
+  "말로 색 바꾸기"를 죽인다(S4).
+- ✅ 중립 명도 단계가 토큰 표에 없으면 **slate 스케일만**(`text-slate-400` 등). ❌ gray·zinc·stone 혼용,
+  유채색 팔레트(rose·emerald 등) 직접 사용 금지 — 새 색이 필요하면 **지어내지 말고 보고**한다.
+- 간격·타이포·라운드·섀도는 **Tailwind 기본 스케일**(`p-4`·`text-2xl`·`rounded-lg`·`shadow-sm`)을 쓴다.
+  임의값(`[...]`)은 **레이아웃 치수에만**(예: `grid-cols-[repeat(auto-fill,minmax(240px,1fr))]`), 색에는 금지.
+
+**레시피**
+- 페이지 `<main className="py-8">` · 섹션 `<section className="mb-12">` · 제목은 base 가 크기를 주므로 `<h1>` 그대로.
+- 버튼은 `src/components/ui/Button`(`<Link>`·`<a>` 에는 `buttonClasses(variant)` 문자열) · 카드는 `ui/Card`.
+- 폼 필드(`<input>`·`<select>`·`<textarea>`)는 base 레이어가 스타일하므로 **맨 요소 그대로** 쓴다.
+
+**절제 — 화려하게 만들지 마라**
+- ❌ `animate-*`·커스텀 keyframes·그라데이션·`backdrop-*`. ✅ `hover:` 색 변화·`transition-colors`·`shadow-sm` 까지.
+
+**전역 토큰 knob — 말로 폰트·모서리·밀도 바꾸기 (계약버전 2)**
+색 외에 **폰트·모서리 둥글기·여백 밀도**도 테넌트가 콘솔에서 "말로" 바꾼다(`site.theme.update`). 값은 **enum**
+뿐이며 `src/lib/theme.ts` 매핑 테이블이 CSS 변수로 변환해 색과 같은 경로(`<html>` inline 주입)로 전 화면에 반영된다.
+
+| knob | enum 값 | 효과 |
+|---|---|---|
+| `font` | `system`(기본) · `pretendard` · `noto-serif-kr` | 전역 폰트(`--font-sans`). system=시스템 산세리프, pretendard=산세리프, noto-serif-kr=명조/세리프 |
+| `radius` | `sharp` · `soft`(기본) · `round` | 모서리 둥글기 — `rounded-*` 스케일 전체를 배수 조정(sharp=각짐, round=곱절) |
+| `density` | `compact` · `cozy`(기본) | 여백 밀도 — `--spacing` 베이스 조정으로 `p-*`·`gap-*` 등 전 간격 유틸리티가 일괄 스케일 |
+
+- ✅ 폰트·모서리·밀도 변경 요청("폰트 바꿔줘", "모서리 각지게", "더 촘촘하게")은 **코드 수정이 아니라 이 knob** 이다 —
+  콘솔에서 바뀌고 재코딩 불요. ❌ 임의 폰트(`font-['Comic Sans']`)·`font-face`·개별 요소 라운드 하드코딩으로 우회 금지.
+- 새 knob 값(예: 다른 폰트)이 필요하면 **지어내지 말고 보고**한다 — enum 확장은 계약버전 증가를 동반한다.
+
+**테마 동작 — 배선을 건드리지 마라**
+- 테넌트 색은 `getSiteConfig().themeColors` → **루트 `layout` 이 `<html>` 의 CSS 변수로 주입**한다. 이 배선
+  (layout 의 테마 주입·`src/lib/theme.ts`)을 제거·우회하지 마라. **색 변경에 코드 수정이 필요하면 설계 위반**이다 —
+  콘솔에서 색을 바꾸면 재코딩 없이 반영되는 것이 정상이다.

package/package.json

@@ -0,0 +1,49 @@
+{
+    "name": "@zalkera/client",
+    "version": "0.6.1",
+    "description": "zalkera 헤드리스 CMS 공개 API 클라이언트 (테넌트 사이트용)",
+    "license": "MIT",
+    "author": "Credium Co., Ltd.",
+    "type": "module",
+    "publishConfig": {
+        "access": "public"
+    },
+    "keywords": [
+        "oneque",
+        "headless",
+        "commerce",
+        "cms",
+        "api-client",
+        "sdk"
+    ],
+    "homepage": "https://zalkera.com",
+    "files": [
+        "dist",
+        "llms.txt"
+    ],
+    "main": "./dist/index.cjs",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js",
+            "require": "./dist/index.cjs"
+        }
+    },
+    "scripts": {
+        "build": "tsup",
+        "dev": "tsup --watch",
+        "typecheck": "tsc --noEmit",
+        "test": "vitest run",
+        "test:watch": "vitest"
+    },
+    "engines": {
+        "node": ">=18"
+    },
+    "devDependencies": {
+        "tsup": "^8.3.5",
+        "typescript": "^5.7.2",
+        "vitest": "^2.1.8"
+    }
+}