@zalkera/client 0.7.0 → 0.8.0

package/llms.txt

@@ -14,9 +14,12 @@
 ## 1. 설치·초기화
 
 ```bash
-npm i ./zalkera-client-0.6.0.tgz   # 배포 tarball(심볼릭 링크 말고 tarball — Turbopack 이슈)
+npm install @zalkera/client        # 공개 npm (MIT)
 ```
 
+- 버전 못 박기: tarball 을 `vendor/` 에 넣어 써도 결과는 동일하다.
+- ❌ 디렉터리 심링크(`file:<dir>`) 금지 — Next 16 Turbopack 이 프로젝트 밖을 못 읽어 깨진다.
+
 ```ts
 // lib/zalkera.ts — 서버 전용 싱글턴
 import { createZalkeraClient } from "@zalkera/client";
@@ -31,6 +34,8 @@ export const zalkera = createZalkeraClient({
 - `.env`: `ZALKERA_API_BASE`, `ZALKERA_TENANT`, (선택)`ZALKERA_STOREFRONT_KEY`. **절대 클라이언트 컴포넌트에서 import 하지 말 것** — baseUrl·시크릿 노출.
 - `secretKey`는 진짜 비밀이다 — `NEXT_PUBLIC_*` 접두사·클라이언트 번들 금지. 서버 `.env`에만. 안 주면 종전대로 `tenant`(X-Tenant)만으로 동작(하위호환).
 - 모든 메서드는 성공 시 데이터를, 실패 시 `ZalkeraError`(`.status`, `.code`, `.isRateLimited`, `.isStorefrontKeyError`, `.validationErrors`)를 던진다.
+- **경로 파라미터는 라이브러리가 인코딩한다** — slug·주문번호·id 를 넘기기 전에 `encodeURIComponent` 를 직접 씌우지 마라(이중 인코딩된다). 쿼리 파라미터도 마찬가지다.
+- **`baseUrl` 은 최종 오리진이어야 한다** — 클라이언트는 리다이렉트를 따라가지 않는다(따라가면 `X-Storefront-Key` 가 다른 오리진으로 샌다). 백엔드가 3xx 를 주면 502 `UPSTREAM_REDIRECT`.
 
 ## 2. 왜 서버 사이드인가 (중요)
 
@@ -61,9 +66,15 @@ await zalkera.submitInquiry(input, { clientIp: ip });
 
 ### 커머스 — 카탈로그(공개)
 - `listProducts({productType?, keyword?, page?, size?, sort?})` → `Paginated<ProductSummary>` (카드용: slug·name·priceFrom·inStock)
-- `getProduct(slug)` → `ProductDetail { name, productType, variants[] }`
+- `getProduct(slug)` → `ProductDetail { id, slug, name, description, productType, coverAssetId, seo, variants[] }`
+  - `seo` 는 **JSON 문자열 패스스루**(백엔드가 검증 안 함·미설정이면 null). 권장 구조는 `{"title","description"}` —
+    `SiteConfig.seoDefaults` 와 같은 모양이다. **파싱 실패해도 죽으면 안 된다**(`parseConfig` 로 읽고, 없으면 상품명으로 강하).
 - `listProductCategories()` → `ProductCategory[]`
 - **variant 가 판매 단위다.** 가격·재고·장바구니·주문은 전부 `variant.id` 기준. 단순 상품도 variant 1개.
+  `ProductVariant { id, sku, optionSignature, price, compareAtPrice, currency, inStock, available }`
+  - `optionSignature` 는 옵션 조합 표시용 문자열("레드/XL") — 단순 상품은 **빈 문자열**이라 그때는 안 그린다.
+  - `compareAtPrice` 는 정가(취소선용). null 이면 할인 아님 — **0 과 혼동하지 마라**.
+  - 금액 표기는 `currency` 를 따른다. 하드코딩하지 마라.
 - `variant.inStock`(불리언)·`variant.available`(추적 재고 수량, 무한재고면 null)로 재고 표시.
 - `productType`: `PHYSICAL`(배송)·`DIGITAL`(즉시)·`SERVICE`(예약).
   **`SERVICE` 는 장바구니·체크아웃을 타지 않는다** — 별도 예약 흐름(§4.6). 담기 시도는 400 이다.
@@ -108,11 +119,65 @@ await zalkera.submitInquiry(input, { clientIp: ip });
 ### 커머스 — 결제·주문·배송
 - `checkout(input, session)` → `OrderDetail`  (input: `{ buyerName, buyerPhone, buyerEmail?, shipTo? }`)
   - 주문 생성 시 가격 스냅샷 동결 + 재고 원자적 차감. 재고 부족이면 409. 상태 `PENDING_PAYMENT`.
-- `startPayment(orderNo, access)` → `{ paymentUrl }` — 고객을 paymentUrl 로 리다이렉트.
+- `startPayment(orderNo, access)` → `PaymentSession { paymentUrl, pgPaymentId, widget? }`
+  - **`widget` 유무가 분기다**: 있으면 위젯형(내 사이트에서 결제창), 없으면 `paymentUrl` 로 리다이렉트(§4.3).
+  - `widget` 에는 **브라우저 노출이 전제된 값만** 담긴다(토스: `vendor:"TOSS_PAYMENTS"`·`clientKey`·`orderId`·`amount`·`orderName`). PG secretKey 는 안 들어온다.
+  - **키 구성은 벤더마다 다르다** — `widget.vendor` 로 분기해 읽는다.
+- `confirmPayment(orderNo, providerParams, access)` → `void` — **위젯형 전용** 승인 확정.
+  성공 콜백 파라미터(`{ paymentKey }` 등)를 그대로 넘긴다. 금액은 안 넘겨도 된다 —
+  서버가 **저장된 주문 금액**으로 PG 에 직접 묻는다(브라우저 금액 조작 무효).
 - `getOrder(orderNo, access)` · `listMyOrders(accessToken,{page,size})` · `cancelOrder(orderNo, access)`
   · `completeOrder(orderNo, access)` · `getShipment(orderNo, access)`
 - `access = { accessToken? }`(로그인) **또는 `{ phone? }`(게스트, 주문 시 남긴 연락처)**.
 
+### 계약 헬퍼 — 직접 짜지 말고 이걸 부른다
+
+이 패키지는 **API 클라이언트이면서 계약 부품의 운반체**다. 아래는 전부 `@zalkera/client` 에서 import 한다 —
+프로젝트 안에 `lib/safeUrl.ts`·`sections/parse.ts` 를 새로 만들지 마라(사본이 갈라지면 수리가 안 퍼진다).
+
+- `safeLinkUrl(raw)` → `string` — **모든 `href` 는 이걸 태운다.** 콘솔 입력이라 `javascript:` 가 들어올 수 있다(저장형 XSS).
+- `parseConfig<T>(config)` → `T | null` — 섹션 `config` JSON 파싱. **절대 throw 하지 않는다**(실패 시 null).
+- `asString(v)` / `asId(v)` — 형이 안 맞으면 `undefined`.
+- `asIdArray(v)` / `asObjectArray(v)` — **빈 배열**로 강하한다(undefined 아님).
+  빈 배열은 truthy 라 `if (items)` 로 결측을 판별하면 안 된다 — `items.length` 을 봐라.
+- 위 가드로 **필수 값이 없으면 그 섹션만 안 그린다**. 페이지 전체가 죽으면 안 된다.
+- `mediaSrc(assetId)` → `/media/{id}` **경로 문자열**. 이미지는 전부 이걸 통한다.
+  전제: 프로젝트에 `app/media/[id]/route.ts` 프록시 라우트가 있어야 한다(스타터에 있다).
+  이 헬퍼는 경로만 만든다 — 라우트를 안 만들면 이미지가 404 다.
+- `SECTION_CONTRACT` / `SECTION_CONTRACT_REV` / `sectionsOfVertical(vertical)` — 아는 섹션 어휘의 코드 표현(§9).
+  타입·키를 **지어내지 말고** 여기서 확인한다.
+- `parseThemeColors(raw)` → `ParsedTheme` — 테마 토큰 파서(§8). 화이트리스트라 임의 CSS 가 안 들어온다.
+
+### ISR 캐시 태그 (`ReadOptions`)
+
+읽기 메서드는 마지막 인자로 `{ tags: [...] }` 를 받는다. 넘기면 그 fetch 에 `next.tags` 가 실려
+**백엔드가 `revalidateTag` 로 온디맨드 무효화**한다 — 테넌트가 콘솔에서 고친 것이 즉시 반영되는 경로다.
+
+```ts
+const config = await zalkera.getSiteConfig({ tags: ["site-config"] });
+const product = await zalkera.getProduct(slug, { tags: ["products", `product:${slug}`] });
+```
+
+**백엔드가 실제로 발화하는 태그는 둘뿐이다**(실측 — `OperationRegistryChangeApplier`):
+
+| 콘솔에서 바뀐 것 | 발화 태그 |
+|---|---|
+| 테마·레이아웃·회사정보(`site.*`) | `site-config` |
+| 상품·가격·재고(`product.*`·`inventory.*`) | `products` |
+| 그 밖(예약·게시물·미지의 op) | 태그 없이 `"/"` 경로 무효화로 폴백 |
+
+- **`product:{slug}` 는 기대하지 마라.** 백엔드가 일부러 안 붙인다 — 오퍼레이션 페이로드의 상품 참조가
+  고객이 말로 지시한 모호 참조라 slug 와 일치한다는 보장이 없다. 상품 페이지도 `products` 로 받는다.
+- **모든 페이지 fetch 에 `site-config` 를 동승시켜라.** 테마·레이아웃은 전 페이지에 영향인데,
+  발화 태그는 `site-config` 하나뿐이라 이걸 안 달면 그 페이지만 옛 테마로 남는다.
+
+```ts
+// 페이지 라우트 — 자기 태그 + site-config 동승
+const page = await zalkera.getPage(slug, { tags: ["site-config", "pages", `page:${slug}`] });
+```
+
+- **안 넘기면 세그먼트 기본 캐시만 걸린다** — 콘솔에서 고쳐도 화면이 안 바뀐다는 신고가 대개 이것이다.
+
 ## 4. 레시피
 
 ### 4.1 상품 목록 페이지 (RSC)
@@ -154,11 +219,11 @@ export async function POST(req: Request) {
      //   → 스타터의 checkout/page.tsx(openWidget)·payment/complete/page.tsx 를 그대로 쓴다
      await zalkera.confirmPayment(orderNo, { paymentKey }, access);   // BFF 경유
    } else {
-     redirect(session.paymentUrl);   // 리다이렉트형(PayOneQ 등)
+     redirect(session.paymentUrl);   // 리다이렉트형(PG 결제창으로 이동)
    }
    ```
    `widget` 유무로만 분기한다 — **벤더 이름으로 분기하지 마라**(벤더가 늘어난다).
-3. 페이원큐 결제창에서 결제. **결과는 서버 웹훅으로 백엔드가 처리**(프론트는 관여 안 함).
+3. PG 결제창에서 결제. **결과는 서버 웹훅으로 백엔드가 처리**(프론트는 관여 안 함).
 4. returnUrl 로 돌아오면 `getOrder(orderNo, access)` 로 상태 확인(잠시 PENDING 일 수 있음 → PAID 폴링/새로고침).
 
 > ⚠️ returnUrl·successUrl 콜백의 "성공"을 **신뢰하지 말 것**. 진짜 확정은 백엔드가 한다 — 웹훅(리다이렉트형)
@@ -283,7 +348,7 @@ if (booking.orderNo) {                  // status=PENDING
   `export const dynamic='force-dynamic'`/`fetch(...,{cache:'no-store'})` **금지**(per-page SSR 유발).
   실시간·개인화 데이터(라이브 재고·개인화)는 **클라이언트 컴포넌트(아일랜드)**로 가져오고, 상태 변경
   (장바구니·주문)은 **BFF route handler** 로 한다. 신선도는 **온디맨드 revalidate**(백엔드 데이터 변경 시
-  `POST /api/revalidate`)로 지킨다. 동적 SSR 이 꼭 필요하면(예: 검색) **정당화 주석**(`// oneque-allow-dynamic:
+  `POST /api/revalidate`)로 지킨다. 동적 SSR 이 꼭 필요하면(예: 검색) **정당화 주석**(`// zalkera-allow-dynamic:
   <이유>`)이 필요하다 — 서버 동적 렌더는 상시 런타임 원가라 CI validator(§5)가 SEO 라우트에서 강제 차단한다.
 
 ## 5.1 산출물 규범 — 발견되는 사이트 (필수)
@@ -343,6 +408,13 @@ catch (e) {
   - `STOREFRONT_KEY_REQUIRED`(401) — 백엔드 `required` 인데 키 없음/무효 → `secretKey` 옵션 설정(콘솔 발급→서버 `.env`).
   - `TENANT_MISMATCH`(403) — `secretKey` 가 `tenant` 와 다른 테넌트의 키 → 두 값 정합 확인.
   - 이 두 코드는 SDK 가 안내 메시지를 매핑해 둔다(`e.message` 그대로 로그에 유용).
+- **SDK 가 직접 만드는 코드(백엔드 `ErrorCode` 가 아니다)** — 전부 502이고 **상류·배선 문제**라, 재시도로 풀리지 않는다:
+  - `UPSTREAM_REDIRECT` — 백엔드가 3xx 로 응답했다. **클라이언트는 리다이렉트를 따라가지 않는다**(따라가면
+    `X-Storefront-Key`·`X-Tenant`·`X-Cart-Session` 이 제3자 오리진에 그대로 전달된다). 원인은 대개 `baseUrl`
+    오배선이다 — http↔https 승격, www 유무, 프록시의 경로 리라이트를 보고 **`baseUrl` 을 최종 오리진으로** 고쳐라.
+    이 코드에는 우회 옵션이 없다(보안 불변식이라 스위치를 두지 않는다).
+  - `UPSTREAM_NON_JSON` — 2xx 인데 본문이 envelope 가 아니다(게이트웨이 HTML 등).
+  - `UPSTREAM_UNAVAILABLE` — 502·503·504 에 비JSON 본문.
 - `e.code` = 백엔드 `ErrorCode` enum 이름. 엔드포인트별 발생 코드 목록의 정본은 **OpenAPI**다.
 - 코드 이름은 **전역 유일이 아니다**(ORDER_NOT_FOUND 가 여러 도메인에 있다) — 분기는 그 엔드포인트 문맥에서.
 - 코드를 안 싣는 구버전 백엔드에서는 `e.code` 가 HTTP 사유구("Conflict")로 **폴백**한다. 폴백 값에
@@ -350,9 +422,12 @@ catch (e) {
 
 ## 7. 결제 파트너
 
-결제·정산은 **페이원큐(PayOneQ)** 가 실행한다. 프론트는 카드정보를 절대 다루지 않는다(PCI 범위 밖).
+결제·정산은 **제3자 PG(결제대행사)** 에 위임한다. 프론트는 카드정보를 절대 다루지 않는다(PCI 범위 밖).
 `startPayment` 가 준 URL 로 보내고, 결과는 백엔드가 웹훅으로 받아 주문 상태를 바꾼다.
 
+**어느 PG 인지에 의존하는 분기를 짜지 마라** — PG 는 교체될 수 있다. 프론트가 보는 계약(`startPayment` 가
+주는 리다이렉트 URL, 웹훅 뒤에 바뀌는 주문 상태)은 그대로다.
+
 ## 8. 스타일 규약 — Tailwind v4 + 테마 토큰 (필수)
 
 스타터(템플릿)는 **Tailwind v4** 와 **테마 토큰**으로 스타일한다. 화면을 그릴 때 아래를 지킨다 — 어기면
@@ -440,23 +515,29 @@ CI validator **S6** 가 좌변 잔존을 error 로 막는다.
 
 ```ts
 const page = await zalkera.getPage("home");
-page.sections // [{ id, type: "HERO", sortOrder: 0, config: "{\"title\":\"…\"}" }, …]
+page.sections // [{ type: "HERO", sortOrder: 0, config: "{\"title\":\"…\"}" }, …]
 ```
 
 **왜 이 구조인가**: 콘텐츠가 마크업에 박히지 않고 계약을 타므로, 테넌트가 콘솔에서·"말로" 고친 것이 재코딩 없이
 반영된다("FAQ 에 배송 질문 추가해줘"). **마크업에 문구를 하드코딩하면 이 경로가 죽는다.**
 
 **규약**
-- `config` 는 **문자열**이다. 파싱은 반드시 실패 허용으로(스타터의 `components/sections/parse.ts` 가 본보기 —
-  절대 throw 하지 않는다). 필수 필드가 없으면 **그 섹션만 안 그린다**. 페이지 전체가 죽으면 안 된다.
+- `config` 는 **문자열**이다. 파싱은 `parseConfig` + `asString`/`asId`/`asIdArray`/`asObjectArray` 로 한다
+  (이 패키지가 export — 절대 throw 하지 않는다). 필수 필드가 없으면 **그 섹션만 안 그린다**.
+  페이지 전체가 죽으면 안 된다.
 - **미지 타입은 조용히 건너뛴다.** 어휘는 append-only 라 백엔드가 타입을 늘려도 옛 사이트가 깨지지 않아야 한다.
   `default:` 에서 에러·경고를 내지 마라 — 그게 계약이다.
-- 이미지는 `assetId`(숫자)다. `getMediaUrl(id)`(스타터의 `mediaSrc()`)로 프록시 경유해 그린다.
-- **모든 href 는 `lib/safeUrl` 을 태운다.** 콘솔 입력이라 `javascript:` 가 들어올 수 있다(저장형 XSS).
+- 이미지는 `assetId`(숫자)다. `mediaSrc(id)`(이 패키지 export)로 프록시 경유해 그린다.
+- **모든 href 는 `safeLinkUrl()` 을 태운다.** 콘솔 입력이라 `javascript:` 가 들어올 수 있다(저장형 XSS).
 - 자유 HTML 은 없다 — plain text + 줄바꿈뿐(`whitespace-pre-wrap`).
 - 타입·키를 **지어내지 마라.** 계약 정본은 `SECTION_CONTRACT`(이 패키지가 export)이고, 필요한 어휘가 없으면
   만들지 말고 **보고**한다.
 
+**디스패치는 직접 짠다** — `type` 으로 컴포넌트를 고르는 `switch` 하나면 된다. 위 규약에 더해 둘을 지켜라:
+
+- **`sortOrder` 로 한 번 더 정렬한다.** 서버가 정렬해 주지만 순서가 틀리면 화면에서 바로 티가 나는 종류다.
+- **key 는 `type`+`sortOrder`+index 로 짠다.** `PageSection` 계약에 id 가 없어(실측) 순수 인덱스보다 낫다.
+
 **어휘 (12종)** — `vertical` 은 콘솔 픽커 그룹핑용이지 사용 제한이 아니다(GENERAL 은 뷰티 테넌트도 쓴다).
 
 | type | vertical | config (필수는 굵게) | JSON-LD |

package/package.json

@@ -1,50 +1,51 @@
 {
-  "name": "@zalkera/client",
-  "version": "0.7.0",
-  "description": "zalkera 헤드리스 CMS 공개 API 클라이언트 (테넌트 사이트용)",
-  "license": "MIT",
-  "author": "Credium Co., Ltd.",
-  "type": "module",
-  "publishConfig": {
-    "access": "public"
-  },
-  "keywords": [
-    "zalkera",
-    "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"
+    "name": "@zalkera/client",
+    "version": "0.8.0",
+    "description": "zalkera 헤드리스 CMS 공개 API 클라이언트 (테넌트 사이트용)",
+    "license": "MIT",
+    "author": "Credium Co., Ltd.",
+    "type": "module",
+    "publishConfig": {
+        "access": "public"
+    },
+    "keywords": [
+        "zalkera",
+        "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",
+        "prepublishOnly": "npm run typecheck && npm test && npm run build"
+    },
+    "engines": {
+        "node": ">=18"
+    },
+    "devDependencies": {
+        "@types/node": "^22.10.2",
+        "tsup": "^8.3.5",
+        "typescript": "^5.7.2",
+        "vitest": "^2.1.8"
     }
-  },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "prepublishOnly": "npm run typecheck && npm test && npm run build"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "devDependencies": {
-    "tsup": "^8.3.5",
-    "typescript": "^5.7.2",
-    "vitest": "^2.1.8"
-  }
 }