@zalkera/client 0.7.0 → 0.8.0

package/README.md

@@ -7,43 +7,6 @@
 - 동작: 응답 껍데기(`ApiResponse<T>`)를 벗겨 `data`만 반환, 실패는 `ZalkeraError`로 throw.
 - 전제: **서버 사이드 전용**(RSC·route handler·server action). 브라우저 직접 호출 미지원 ([서버 사이드 전용](#서버-사이드-전용-중요) 참고).
 
-## `@oneque/client` 에서 옮겨오기
-
-패키지 이름과 공개 심볼이 함께 바뀌었다(브랜드 개명). 옛 패키지는 발행 상태로 남지만 더는 갱신되지 않는다.
-
-```diff
-- "@oneque/client": "^0.6.0"
-+ "@zalkera/client": "^0.6.1"
-```
-
-```diff
-- import {createOnequeClient, OnequeError} from "@oneque/client";
-+ import {createZalkeraClient, ZalkeraError} from "@zalkera/client";
-```
-
-| 옛 이름 | 새 이름 |
-|---|---|
-| `createOnequeClient` | `createZalkeraClient` |
-| `OnequeError` | `ZalkeraError` |
-| `OnequeClient` | `ZalkeraClient` |
-| `OnequeClientOptions` | `ZalkeraClientOptions` |
-
-**환경변수 이름도 `ZALKERA_*` 로 바뀌었다**(2026-07-26 컷오버). 관리형 서빙(잘커라가 띄우는 사이트)은
-인프라가 새 이름으로 주입하므로 할 일이 없다. **자기 인프라로 돌리는 BYO 사이트는 `.env` 의 이름을 직접
-바꿔야 한다** — 구 이름 폴백은 제거됐다:
-
-| 옛 이름 | 새 이름 |
-|---|---|
-| `ONEQUE_API_BASE` | `ZALKERA_API_BASE` |
-| `ONEQUE_TENANT` | `ZALKERA_TENANT` |
-| `ONEQUE_STOREFRONT_KEY` | `ZALKERA_STOREFRONT_KEY` |
-| `ONEQUE_SITE_URL` | `ZALKERA_SITE_URL` |
-
-동적 SSR 정당화 마커도 `zalkera-allow-dynamic` 이 새 이름이지만 기존 `oneque-`/`oneq-` 마커를 계속 수용한다.
-`x-oneque-revalidate-secret` **헤더 이름은 그대로다** — 백엔드가 보내는 와이어 이름이라 별도 전환이 필요하다.
-
-기능·API 동작은 동일하다 — 이름만 바뀌었다.
-
 ## 설치
 
 ```bash
@@ -108,6 +71,7 @@ await zalkera.submitInquiry({name, email, subject, message}, {clientIp});
 | `getPost(slug)` | `GET /api/public/posts/{slug}` | `PostDetail` |
 | `recordPostView(slug, ctx?)` | `POST /api/public/posts/{slug}/view` | `boolean` |
 | `getPage(slug, options?)` | `GET /api/public/pages/{slug}` | `PageContent` |
+| `listPages(params?, options?)` | `GET /api/public/pages` | `Paginated<PageSummary>` |
 | `listMenus(options?)` | `GET /api/public/menus` | `Menu[]` |
 | `getMediaUrl(id)` | `GET /api/public/media/{id}/url` | `MediaUrl` |
 | `submitInquiry(input, ctx?)` | `POST /api/public/inquiries` | `InquiryCreated` |
@@ -124,6 +88,7 @@ await zalkera.submitInquiry({name, email, subject, message}, {clientIp});
 | `getProductReviewSummary(productId, options?)` | `GET /api/public/products/{id}/reviews/summary` | `RatingSummary` |
 | `createProductReview(productId, input, accessToken)` | `POST /api/shop/products/{id}/reviews` | `Review` |
 
+- `listPages`는 **열거 전용**(본문 없음 — sitemap용). `size` 상한 100.
 - 후기 조회는 **숫자 `productId`**(slug 아님) — `getProduct(slug).id`로 획득.
 - 후기 작성은 로그인 필수 + 구매검증(본인·배송완료 이상·상품 일치).
 
@@ -246,6 +211,20 @@ try {
 }
 ```
 
+### SDK 가 직접 만드는 에러 코드
+
+백엔드 `ErrorCode`가 아니라 클라이언트가 붙이는 코드다. 전부 `status === 502`이고 **배선·상류 문제**라 재시도로 풀리지 않는다.
+
+| `code` | 뜻 / 처방 |
+|---|---|
+| `UPSTREAM_REDIRECT` | 백엔드가 3xx로 응답했다. **클라이언트는 리다이렉트를 따라가지 않는다** — 따라가면 `X-Storefront-Key`·`X-Tenant`·`X-Cart-Session`이 제3자 오리진에 그대로 전달되기 때문이다. `baseUrl`이 **최종 오리진**인지 확인하라(http↔https 승격·www 유무·프록시 경로 리라이트). 우회 옵션은 없다(보안 불변식). |
+| `UPSTREAM_NON_JSON` | 2xx인데 본문이 envelope가 아니다(게이트웨이 HTML 등). |
+| `UPSTREAM_UNAVAILABLE` | 502·503·504에 비JSON 본문. 상류 장애. |
+
+### 경로 파라미터
+
+- slug·주문번호·id 등 **경로 파라미터는 라이브러리가 인코딩한다**. 넘기기 전에 `encodeURIComponent`를 직접 씌우지 마라 — 이중 인코딩된다.
+
 ### 시크릿 키 관련 에러
 
 - `401 STOREFRONT_KEY_REQUIRED` — 백엔드 `required` 모드인데 키 없음/무효. `secretKey` 설정 필요.

package/dist/index.cjs

@@ -62,13 +62,18 @@ var ZalkeraError = class _ZalkeraError extends Error {
   }
 };
 var STOREFRONT_KEY_MESSAGES = {
-  STOREFRONT_KEY_REQUIRED: "\uC2A4\uD1A0\uC5B4\uD504\uB860\uD2B8 \uC2DC\uD06C\uB9BF \uD0A4\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4. createZalkeraClient \uC758 secretKey \uC635\uC158\uC744 \uC124\uC815\uD558\uC138\uC694 (\uD30C\uD2B8\uB108 \uCF58\uC194\uC5D0\uC11C \uBC1C\uAE09 \u2192 \uC11C\uBC84 .env \uC758 ONEQUE_STOREFRONT_KEY). \uBE0C\uB77C\uC6B0\uC800 \uBC88\uB4E4\uC5D0 \uB123\uC9C0 \uB9C8\uC138\uC694.",
+  STOREFRONT_KEY_REQUIRED: "\uC2A4\uD1A0\uC5B4\uD504\uB860\uD2B8 \uC2DC\uD06C\uB9BF \uD0A4\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4. createZalkeraClient \uC758 secretKey \uC635\uC158\uC744 \uC124\uC815\uD558\uC138\uC694 (\uD30C\uD2B8\uB108 \uCF58\uC194\uC5D0\uC11C \uBC1C\uAE09 \u2192 \uC11C\uBC84 .env \uC758 ZALKERA_STOREFRONT_KEY). \uBE0C\uB77C\uC6B0\uC800 \uBC88\uB4E4\uC5D0 \uB123\uC9C0 \uB9C8\uC138\uC694.",
   TENANT_MISMATCH: "secretKey \uAC00 tenant \uC635\uC158\uACFC \uB2E4\uB978 \uD14C\uB10C\uD2B8\uC758 \uD0A4\uC785\uB2C8\uB2E4. \uB450 \uAC12\uC774 \uAC19\uC740 \uD14C\uB10C\uD2B8\uC778\uC9C0 \uD655\uC778\uD558\uC138\uC694."
 };
 function isApiErrorBody(value) {
   return typeof value === "object" && value !== null && "message" in value && typeof value.message === "string";
 }
 
+// src/pathSegment.ts
+function seg(v) {
+  return encodeURIComponent(String(v));
+}
+
 // src/client.ts
 var DEFAULT_TIMEOUT_MS = 1e4;
 function createZalkeraClient(options) {
@@ -81,6 +86,9 @@ function createZalkeraClient(options) {
   }
   const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   async function request(path, init) {
+    if (/(^|\/)\.{1,2}(\/|$)/.test(path)) {
+      throw new ZalkeraError(`\uACBD\uB85C\uC5D0 \uC0C1\uB300 \uC138\uADF8\uBA3C\uD2B8\uAC00 \uC788\uC2B5\uB2C8\uB2E4: ${path}`, { status: 400, code: "INVALID_PATH" });
+    }
     const url = new URL(`${baseUrl}/api${path}`);
     if (init?.query) {
       for (const [key, value] of Object.entries(init.query)) {
@@ -106,7 +114,14 @@ function createZalkeraClient(options) {
         method: init?.method ?? "GET",
         headers,
         body: init?.body != null ? JSON.stringify(init.body) : void 0,
-        signal: controller.signal
+        signal: controller.signal,
+        // 리다이렉트를 따라가지 않는다 — **보안 불변식이라 스위치를 두지 않는다**(옵션으로 열면
+        // 그 옵션이 곧 사고 경로가 된다). 기본값 `follow` 로 크로스오리진 3xx 를 따라가면
+        // `X-Storefront-Key`(테넌트 시크릿)·`X-Tenant`·`X-Cart-Session`·`Idempotency-Key` 가
+        // 제3자 오리진에 그대로 전달된다 — undici 는 커스텀 헤더를 벗기지 않는다(실측).
+        // `"error"` 를 쓰지 않는 이유: undici 에서 일반 `TypeError: fetch failed` 로 떨어져
+        // 아래 네트워크 분기에 흡수되고, 그러면 원인(대개 baseUrl 오배선)이 사라진다.
+        redirect: "manual"
       };
       if (init?.next) fetchInit.next = init.next;
       response = await fetchImpl(url.toString(), fetchInit);
@@ -119,6 +134,14 @@ function createZalkeraClient(options) {
     } finally {
       clearTimeout(timer);
     }
+    if (isRedirectResponse(response)) {
+      response.body?.cancel().catch(() => {
+      });
+      throw new ZalkeraError(
+        `\uBC31\uC5D4\uB4DC\uAC00 \uB9AC\uB2E4\uC774\uB809\uD2B8\uB85C \uC751\uB2F5\uD588\uC2B5\uB2C8\uB2E4 (HTTP ${response.status}). \uBCF4\uC548\uC0C1 \uB530\uB77C\uAC00\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4 \u2014 \uB530\uB77C\uAC00\uBA74 \uC694\uCCAD \uD5E4\uB354(\uD14C\uB10C\uD2B8 \uC2DC\uD06C\uB9BF \uD0A4\xB7\uC7A5\uBC14\uAD6C\uB2C8 \uC138\uC158)\uAC00 \uB2E4\uB978 \uC624\uB9AC\uC9C4\uC73C\uB85C \uC0D9\uB2C8\uB2E4. baseUrl \uC774 \uCD5C\uC885 \uC624\uB9AC\uC9C4\uC778\uC9C0 \uD655\uC778\uD558\uC138\uC694(http\u2194https \uC2B9\uACA9, www \uC720\uBB34, \uD504\uB85D\uC2DC\uC758 \uACBD\uB85C \uB9AC\uB77C\uC774\uD2B8).`,
+        { status: 502, code: "UPSTREAM_REDIRECT" }
+      );
+    }
     const text = await response.text();
     const parsed = text ? safeJsonParse(text) : null;
     if (!response.ok) {
@@ -144,18 +167,18 @@ function createZalkeraClient(options) {
         sort: params?.sort
       }
     }),
-    getPost: (slug) => request(`/public/posts/${encodeURIComponent(slug)}`),
-    recordPostView: (slug, context) => request(`/public/posts/${encodeURIComponent(slug)}/view`, {
+    getPost: (slug) => request(`/public/posts/${seg(slug)}`),
+    recordPostView: (slug, context) => request(`/public/posts/${seg(slug)}/view`, {
       method: "POST",
       context
     }),
-    getPage: (slug, options2) => request(`/public/pages/${encodeURIComponent(slug)}`, nextInit(options2)),
+    getPage: (slug, options2) => request(`/public/pages/${seg(slug)}`, nextInit(options2)),
     listPages: (params, options2) => request("/public/pages", {
       query: { page: params?.page, size: params?.size },
       ...nextInit(options2)
     }),
     listMenus: (options2) => request("/public/menus", { next: options2?.tags ? { tags: options2.tags } : void 0 }),
-    getMediaUrl: (id) => request(`/public/media/${id}/url`),
+    getMediaUrl: (id) => request(`/public/media/${seg(id)}/url`),
     submitInquiry: (input, context) => request("/public/inquiries", {
       method: "POST",
       body: input,
@@ -167,7 +190,7 @@ function createZalkeraClient(options) {
       context
     }),
     // ── 커머스: 카탈로그 ────────────────────────────────────
-    getProduct: (slug, options2) => request(`/public/products/${encodeURIComponent(slug)}`, nextInit(options2)),
+    getProduct: (slug, options2) => request(`/public/products/${seg(slug)}`, nextInit(options2)),
     listProducts: (params, options2) => request("/public/products", {
       query: {
         productType: params?.productType,
@@ -180,14 +203,14 @@ function createZalkeraClient(options) {
     }),
     listProductCategories: (options2) => request("/public/product-categories", nextInit(options2)),
     // ── 커머스: 상품후기(공개) ──────────────────────────────
-    listProductReviews: (productId, params, options2) => request(`/public/products/${productId}/reviews`, {
+    listProductReviews: (productId, params, options2) => request(`/public/products/${seg(productId)}/reviews`, {
       query: { page: params?.page, size: params?.size },
       next: options2?.tags ? { tags: options2.tags } : void 0
     }),
-    getProductReviewSummary: (productId, options2) => request(`/public/products/${productId}/reviews/summary`, {
+    getProductReviewSummary: (productId, options2) => request(`/public/products/${seg(productId)}/reviews/summary`, {
       next: options2?.tags ? { tags: options2.tags } : void 0
     }),
-    createProductReview: (productId, input, accessToken) => request(`/shop/products/${productId}/reviews`, { method: "POST", body: input, bearer: accessToken }),
+    createProductReview: (productId, input, accessToken) => request(`/shop/products/${seg(productId)}/reviews`, { method: "POST", body: input, bearer: accessToken }),
     // ── 커머스: 고객 인증 ───────────────────────────────────
     socialLogin: (input) => request("/shop/auth/social", { method: "POST", body: input }),
     refreshSession: (refreshToken) => request("/shop/auth/refresh", { method: "POST", body: { refreshToken } }),
@@ -202,11 +225,11 @@ function createZalkeraClient(options) {
     }),
     createBooking: (accessToken, input) => request("/shop/booking/bookings", { method: "POST", body: input, bearer: accessToken }),
     myBookings: (accessToken) => request("/shop/booking/bookings", { bearer: accessToken }),
-    cancelBooking: (accessToken, bookingCode) => request(`/shop/booking/bookings/${encodeURIComponent(bookingCode)}/cancel`, {
+    cancelBooking: (accessToken, bookingCode) => request(`/shop/booking/bookings/${seg(bookingCode)}/cancel`, {
       method: "POST",
       bearer: accessToken
     }),
-    rescheduleBooking: (accessToken, bookingCode, newSlotId) => request(`/shop/booking/bookings/${encodeURIComponent(bookingCode)}/reschedule`, {
+    rescheduleBooking: (accessToken, bookingCode, newSlotId) => request(`/shop/booking/bookings/${seg(bookingCode)}/reschedule`, {
       method: "POST",
       body: { newSlotId },
       bearer: accessToken
@@ -214,33 +237,33 @@ function createZalkeraClient(options) {
     // ── 커머스: 장바구니 ────────────────────────────────────
     getCart: (session) => request("/shop/cart", shopInit(session)),
     addToCart: (variantId, quantity, session) => request("/shop/cart/items", shopInit(session, { method: "POST", body: { variantId, quantity } })),
-    updateCartItem: (variantId, quantity, session) => request(`/shop/cart/items/${variantId}`, shopInit(session, { method: "PATCH", body: { quantity } })),
-    removeFromCart: (variantId, session) => request(`/shop/cart/items/${variantId}`, shopInit(session, { method: "DELETE" })),
+    updateCartItem: (variantId, quantity, session) => request(`/shop/cart/items/${seg(variantId)}`, shopInit(session, { method: "PATCH", body: { quantity } })),
+    removeFromCart: (variantId, session) => request(`/shop/cart/items/${seg(variantId)}`, shopInit(session, { method: "DELETE" })),
     clearCart: (session) => request("/shop/cart", shopInit(session, { method: "DELETE" })),
     // ── 커머스: 결제·주문·배송 ──────────────────────────────
     checkout: (input, session, idempotencyKey) => request("/shop/checkout", shopInit(session, { method: "POST", body: input, idempotencyKey })),
     confirmPayment: (orderNo, providerParams, access) => request(
-      `/shop/orders/${encodeURIComponent(orderNo)}/payment/confirm`,
+      `/shop/orders/${seg(orderNo)}/payment/confirm`,
       accessInit(access, { method: "POST", body: providerParams })
     ),
     startPayment: (orderNo, access) => request(
-      `/shop/orders/${encodeURIComponent(orderNo)}/payment/session`,
+      `/shop/orders/${seg(orderNo)}/payment/session`,
       accessInit(access, { method: "POST" })
     ),
-    getOrder: (orderNo, access) => request(`/shop/orders/${encodeURIComponent(orderNo)}`, accessInit(access)),
+    getOrder: (orderNo, access) => request(`/shop/orders/${seg(orderNo)}`, accessInit(access)),
     listMyOrders: (accessToken, params) => request("/shop/orders", {
       bearer: accessToken,
       query: { page: params?.page, size: params?.size }
     }),
     cancelOrder: (orderNo, access) => request(
-      `/shop/orders/${encodeURIComponent(orderNo)}/cancel`,
+      `/shop/orders/${seg(orderNo)}/cancel`,
       accessInit(access, { method: "POST" })
     ),
     completeOrder: (orderNo, access) => request(
-      `/shop/orders/${encodeURIComponent(orderNo)}/complete`,
+      `/shop/orders/${seg(orderNo)}/complete`,
       accessInit(access, { method: "POST" })
     ),
-    getShipment: (orderNo, access) => request(`/shop/orders/${encodeURIComponent(orderNo)}/shipment`, accessInit(access))
+    getShipment: (orderNo, access) => request(`/shop/orders/${seg(orderNo)}/shipment`, accessInit(access))
   };
 }
 function nextInit(options) {
@@ -256,6 +279,9 @@ function accessInit(access, extra) {
     query: access.phone ? { phone: access.phone } : void 0
   };
 }
+function isRedirectResponse(response) {
+  return response.type === "opaqueredirect" || response.status >= 300 && response.status < 400;
+}
 function safeJsonParse(text) {
   try {
     return JSON.parse(text);
@@ -327,7 +353,7 @@ function asId(value) {
   return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : void 0;
 }
 function mediaSrc(assetId) {
-  return `/media/${assetId}`;
+  return `/media/${seg(assetId)}`;
 }
 
 // src/theme.ts