@zalkera/client 0.18.0 → 0.20.0

package/dist/index.d.ts

@@ -127,78 +127,7 @@ interface ListPostsParams {
     /** Spring 정렬 표현. 예: `"publishedAt,desc"`. */
     sort?: string;
 }
-/**
- * `PublicPageSummaryResponse` — 페이지 **목록 카드**. 열거 전용이라 본문·섹션·seo 가 없다.
- *
- * 이 표면의 존재 이유는 sitemap 이다: 상세([PageContent])로 100개를 열거하면 섹션·본문까지 딸려와
- * 크롤러 한 번에 카탈로그 전체를 붓게 된다. 상세가 필요하면 slug 로 [ZalkeraClient.getPage] 를 부른다.
- */
-interface PageSummary {
-    slug: string;
-    title: string;
-    publishedAt: string | null;
-    /** 마지막 수정 시각 — sitemap `lastModified` 의 입력. 없으면 소비자가 필드를 생략한다. */
-    modified: string | null;
-}
-/** 페이지 목록 질의. page 는 0-based. 정렬은 서버 고정(제목 오름차순)이라 `sort` 가 없다. */
-interface ListPagesParams {
-    page?: number;
-    /** 서버 상한 100 — 초과 요청은 100 으로 잘린다. */
-    size?: number;
-}
-/**
- * 페이지 섹션 — 구조화된 페이지 구성 요소.
- *
- * `type` 은 **문자열 그대로 둔다**(union 아님). 백엔드 `SectionType` 이 append-only 계약이라
- * union 으로 못박으면 새 타입이 추가되는 순간 기존 스토어프론트가 타입 에러로 깨진다.
- * 아는 값만 [KnownSectionType] 로 따로 제공한다 — **모르는 타입은 조용히 건너뛰는 게 계약이다.**
- *
- * `config` 는 **파싱하지 않은 raw JSON 문자열**이다(`seo`·`themeColors` 와 같은 사상). 백엔드도
- * 검증하지 않는다 — 사이트 하나 고칠 때마다 백엔드를 배포하지 않으려는 의도다. 파싱은 소비자
- * 몫이고, **깨진 config 는 그 섹션만 건너뛰어야지 페이지를 죽이면 안 된다.**
- *
- * 타입별 config 형상의 **정본은 백엔드 레포 `doc/contracts/section-vocabulary.json`** 이다.
- * 여기에 형상을 다시 적지 않는다 — 두 벌이면 갈라진다(사본 넷이 주석 규약으로 갈라진 사고가 실재).
- * 아는 타입 목록은 [SECTION_CONTRACT] 로 제공한다.
- *
- * ⚠ **섹션은 업무 데이터(상품·갈래)를 가리키지 않는다**(계약 rev 6 · memo142 §1). 종전에는
- * `SERVICE_MENU { categorySlug }` 같은 조회형 변형을 여기 예외로 적어 뒀는데, 그 타입들이 어휘에서
- * 삭제됐다. 진열은 소스가 [listProducts]·[listProductCategories] 를 **직접 호출**해 그린다 — 어디에
- * 뿌릴지도 어떻게 그릴지도 소스의 몫이다.
- */
-interface PageSection {
-    type: string;
-    sortOrder: number;
-    config: string | null;
-}
-/** `PublicPageResponse` — 회사 소개 같은 고정 페이지. */
-interface PageContent {
-    id: number;
-    slug: string;
-    title: string;
-    /** 레거시 마크다운 본문. [sections] 가 있으면 무시된다. */
-    content: string | null;
-    publishedAt: string | null;
-    /**
-     * SEO 오버라이드 JSON 문자열(스키마리스 — 백엔드가 검증하지 않는다). 미설정이면 null.
-     * 권장 구조: `{"title": "…", "description": "…"}` — 사이트 기본값 [SiteConfig.seoDefaults] 와
-     * 같은 모양이다. `title` 없으면 소비자가 자연 제목(페이지 제목·상품명)으로 강하한다.
-     * **파싱 실패해도 죽으면 안 된다** — 패스스루라 어떤 값이든 올 수 있다.
-     */
-    seo: string | null;
-    /** 있으면 이걸 렌더한다(content 는 무시). 비었으면 [content] 폴백. 순서는 서버가 정렬해 준다. */
-    sections: PageSection[];
-}
 type MenuPosition = "HEADER" | "FOOTER";
-/** `PublicMenuResponse` — 재귀 트리(children). */
-interface Menu {
-    id: number;
-    position: MenuPosition;
-    label: string;
-    url: string;
-    sortOrder: number;
-    children: Menu[];
-}
 /** `PublicMediaUrlResponse` — presigned 다운로드 URL. `expiresAt` 전까지만 유효하다. */
 interface MediaUrl {
     url: string;
@@ -692,39 +621,28 @@ interface ZalkeraClient {
      *
      * 조회 dedup 은 뷰어 IP·UA 를 쓴다. 서버 사이드에서 부를 때는 [RequestContext.clientIp] 로
      * 원 방문자 IP 를 넘겨야 방문자별로 집계된다 — 안 넘기면 전부 서버 IP 하나로 뭉친다.
+     * 값은 [visitorIp] 로 뽑아라(첫 홉 직접 추출 금지 — 방문자가 위조할 수 있다).
      */
     recordPostView(slug: string, context?: RequestContext): Promise<boolean>;
-    /** slug 로 고정 페이지. */
-    /**
-     * slug 로 고정 페이지(섹션 포함). 없으면 404 → [ZalkeraError].
-     * ISR 페이지는 [ReadOptions.tags] 로 캐시 태그를 실을 수 있다 — 백엔드가 발행 시 그 태그만
-     * 콕 집어 revalidate 한다.
-     */
-    getPage(slug: string, options?: ReadOptions): Promise<PageContent>;
-    /**
-     * 발행된 고정 페이지 **목록**(열거 전용·본문 없음).
-     *
-     * sitemap 을 위한 API 다 — 이게 없으면 콘솔·AI 로 만든 페이지가 검색엔진에 열거되지 않는다.
-     * 목록에 실린 slug 는 [getPage] 가 반드시 200 을 준다(가시성 술어가 서버에서 하나로 공유된다).
-     */
-    listPages(params?: ListPagesParams, options?: ReadOptions): Promise<Paginated<PageSummary>>;
-    /** 메뉴 트리(HEADER·FOOTER). */
-    listMenus(options?: ReadOptions): Promise<Menu[]>;
     /** 미디어 presigned 다운로드 URL(만료 있음). */
     getMediaUrl(id: number): Promise<MediaUrl>;
     /**
      * 문의 접수. 성공 시 생성된 문의 id. 레이트리밋이면 429 → `error.isRateLimited`.
      *
      * ⚠️ 서버 사이드(테넌트 route handler)에서 부를 때는 [RequestContext.clientIp] 로 **원 방문자
-     * IP 를 반드시 넘겨야 한다.** 백엔드의 문의 레이트리밋·IP 기록은 `X-Forwarded-For` 첫 홉을
-     * 쓰는데, 안 넘기면 백엔드가 테넌트 서버 IP 하나만 보고 몇 건 뒤 **모든 방문자**를 429 로 막는다.
+     * IP 를 반드시 넘겨야 한다.** 안 넘기면 백엔드가 테넌트 서버 IP 하나만 보고 몇 건 뒤 **모든 방문자**
+     * 를 429 로 막는다.
+     *
+     * ⚠️ 그 값은 **[visitorIp] 로 뽑아라.** `x-forwarded-for` 의 **첫 홉을 직접 쓰지 마라** — 첫 엔트리는
+     * 방문자가 요청에 손으로 실은 값이라 레이트리밋이 한 줄로 우회된다(백엔드는 첫 홉을 쓰지 않는다.
+     * 신뢰 프록시 홉 기반으로 채택한다). 보장 경계·홉 수 선언은 [visitorIp] 문서 참조.
      */
     submitInquiry(input: InquiryInput, context?: RequestContext): Promise<InquiryCreated>;
     /**
      * 광고 리드 접수. 문의와 달리 이메일이 선택이고 UTM 추적을 함께 보낸다.
      *
      * ⚠️ [submitInquiry] 와 같은 이유로 서버 사이드에서는 [RequestContext.clientIp] 로 원 방문자
-     * IP 를 넘겨야 한다 — 백엔드 리드 레이트리밋·IP 기록이 그 값을 본다.
+     * IP 를 넘겨야 한다 — 백엔드 리드 레이트리밋·IP 기록이 그 값을 본다. 값은 [visitorIp] 로 뽑는다.
      */
     submitLead(input: LeadInput, context?: RequestContext): Promise<LeadCreated>;
     /** slug 로 공개 상품(ACTIVE) 상세 — variant·재고 가용여부 포함. 없으면 404. ISR 태그는 [ReadOptions]. */
@@ -837,18 +755,18 @@ interface ZalkeraClient {
      * 리다이렉트형 벤더에 부르면 404(`PG_CONFIG_NOT_FOUND`).
      */
     confirmPayment(orderNo: string, providerParams: Record<string, string>, access: OrderAccess): Promise<void>;
-    /** 주문 조회 — 본인(accessToken) 또는 게스트(phone). */
+    /** 주문 조회 — 본인(accessToken) 또는 게스트(phone). 인가 실패가 누적되면 429. */
     getOrder(orderNo: string, access: OrderAccess): Promise<OrderDetail>;
     /** 내 주문 목록(로그인 필수). */
     listMyOrders(accessToken: string, params?: {
         page?: number;
         size?: number;
     }): Promise<Paginated<OrderSummary>>;
-    /** 주문 취소(미결제만) — 본인 또는 게스트(phone). */
+    /** 주문 취소(미결제만) — 본인 또는 게스트(phone). 인가 실패가 누적되면 429. */
     cancelOrder(orderNo: string, access: OrderAccess): Promise<OrderDetail>;
-    /** 구매 확정(배송완료 후) — 본인 또는 게스트(phone). */
+    /** 구매 확정(배송완료 후) — 본인 또는 게스트(phone). 인가 실패가 누적되면 429. */
     completeOrder(orderNo: string, access: OrderAccess): Promise<OrderDetail>;
-    /** 배송 조회 — 본인 또는 게스트(phone). */
+    /** 배송 조회 — 본인 또는 게스트(phone). 인가 실패가 누적되면 429. */
     getShipment(orderNo: string, access: OrderAccess): Promise<ShipmentInfo>;
 }
 /**
@@ -866,15 +784,28 @@ interface ShopSession {
 interface OrderAccess {
     accessToken?: string;
     phone?: string;
+    /**
+     * ⚠️ 서버 사이드(테넌트 route handler)에서 부를 때는 [RequestContext.clientIp] 로 **원 방문자 IP 를
+     * 선언**하라. 게스트 주문 인가(주문번호+phone)에는 실패 rate-limit 이 걸려 있는데, 선언이 없으면
+     * 백엔드가 보는 IP 가 **테넌트 서버 하나로 뭉쳐** 한 방문자의 실패가 그 사이트 전체를 잠글 수 있다.
+     * 주문번호 축은 그와 무관하게 계속 서므로 방어 자체는 유효하다 — 선언은 **오탐을 줄이는 쪽**이다.
+     */
+    context?: RequestContext;
 }
 /**
- * IP 민감 엔드포인트(문의·조회 비콘)에서 원 방문자를 백엔드에 알리는 컨텍스트.
+ * IP 민감 엔드포인트(문의·리드·조회 비콘)에서 원 방문자를 백엔드에 알리는 컨텍스트.
  *
  * 테넌트 사이트는 서버 사이드에서 이 클라이언트를 부르므로, 백엔드가 보는 소스 IP 는 방문자가
- * 아니라 테넌트 서버다. 방문자 IP 를 `X-Forwarded-For` 로 실어 백엔드가 방문자별로 판단하게 한다.
+ * 아니라 테넌트 서버다. 그래서 방문자 IP 를 **선언**해서 넘긴다 — 전송은 전용 헤더
+ * `X-Zalkera-Client-Ip`(+ 이행기 `X-Forwarded-For` 병행)이고, 백엔드는 **유효 스토어프론트 키가 확인된
+ * 요청에서만** 그 선언을 채택한다. 무키 요청의 선언은 무시되므로 값이 안 반영될 수 있다(그때는 종전대로
+ * 테넌트 서버 IP 로 뭉친다 — 퇴행이 아니라 현상 유지다).
  */
 interface RequestContext {
-    /** 원 방문자 IP — route handler 에서 요청 헤더(x-forwarded-for·x-real-ip)로 뽑아 넘긴다. */
+    /**
+     * 원 방문자 IP. **[visitorIp] 로 뽑아라** — `x-forwarded-for` 첫 홉을 손으로 쓰면 방문자가 위조할 수 있고
+     * (`x-real-ip` 도 프록시마다 달라 신뢰 못 한다), 그 우회는 조용하다. 못 정하면 넘기지 마라(생략 = 백엔드 폴백).
+     */
     clientIp?: string;
 }
 declare function createZalkeraClient(options: ZalkeraClientOptions): ZalkeraClient;
@@ -891,7 +822,7 @@ declare function createZalkeraClient(options: ZalkeraClientOptions): ZalkeraClie
  * `status` 는 거친 분류에만:
  * - `400` + [validationErrors] — 입력값 문제(폼 필드별 메시지 노출)
  * - `404` — 없는 slug/리소스
- * - `429` — IP 레이트리밋(문의 남발). [isRateLimited] 로 편히 판별
+ * - `429` — 레이트리밋(문의·리드 남발, 게스트 주문 인가 실패 누적). [isRateLimited] 로 편히 판별
  * - `5xx` — 서버 오류
  *
  * 네트워크 자체가 실패했거나 응답이 JSON 이 아니면 [status] 가 0 이고 [body] 가 null 이다.
@@ -919,7 +850,13 @@ declare class ZalkeraError extends Error {
         body?: ApiErrorBody | null;
         cause?: unknown;
     });
-    /** IP 레이트리밋(429) — 문의 폼에서 "잠시 후 다시" 를 띄울 때 쓴다. */
+    /**
+     * 레이트리밋(429) — "잠시 후 다시" 를 띄울 때 쓴다.
+     *
+     * 두 갈래다: ⑴ 문의·리드 폼 남발(IP 축) ⑵ **게스트 주문 인가 실패 누적** — 주문번호+연락처로
+     * 여는 주문 조회·취소·구매확정·배송조회·결제세션은 연락처 대입을 막으려고 실패를 센다.
+     * 정상 조회는 세지 않으므로, 이 코드가 뜨면 연락처를 여러 번 틀렸거나 같은 주문에 시도가 몰린 것이다.
+     */
     get isRateLimited(): boolean;
     /**
      * 스토어프론트 시크릿 키 문제(memo78) — 개발자 오배선 신호. `true` 면 `secretKey` 옵션을
@@ -935,9 +872,10 @@ declare class ZalkeraError extends Error {
  * 섹션 어휘 계약 — **정본의 코드 표현**(memo102 §6).
  *
  * 정본은 백엔드 레포의 `doc/contracts/section-vocabulary.json` 이고, 이 파일은 그것을 npm 으로
- * 실어 나르는 **운반체**다. 템플릿 렌더러와 콘솔 zod 스키마가 이 상수를 읽어 자기 커버리지를
- * 기계로 검사한다 — 사본이 갈라진 채 조용히 굳는 것을 막는 게 목적이지, 실시간 동일성이 목적은
- * 아니다(계약이 원래 스큐 내성으로 설계돼 있다: 미지 타입은 스킵).
+ * 실어 나르는 **운반체**다. 스토어프론트 렌더러가 이 상수를 읽어 자기 커버리지를 기계로 검사한다 —
+ * 사본이 갈라진 채 조용히 굳는 것을 막는 게 목적이지, 실시간 동일성이 목적은 아니다(계약이 원래
+ * 스큐 내성으로 설계돼 있다: 미지 타입은 스킵). rev 7 에서 사본은 **둘**이다(이 운반체·렌더러) —
+ * 백엔드 `SectionType` enum 과 콘솔 zod 는 거처(DB)와 함께 퇴역했다(memo144).
  *
  * 두 레포가 갈라져 있어 상호 CI 강제가 불가능하므로 **사람 이음새가 정확히 한 곳** 남는다 —
  * 백엔드 JSON ↔ 이 파일. [SECTION_CONTRACT_REV] 를 백엔드 스펙의 `contractRev` 와 맞춰 두고,
@@ -969,9 +907,17 @@ declare class ZalkeraError extends Error {
  * ⚠ **계약이 스큐 내성이라 이 삭제가 구 사이트를 깨지 않는다** — 렌더러는 미지 타입을 조용히 스킵한다.
  * 어휘를 강제하지도 않는다(memo125 요건 1): 자기 소스에 무엇을 적든 자유이고, 집행은 **우리 산출물인
  * 팩**에만 선다.
+ *
+ * rev 7 = **DB 방언 소거 — 거처가 하나 남았다**(memo144). `page`·`page_section`·`menu` 계열이 퇴역하면서
+ * 정본의 `dialects.id`(숫자 id 표기)가 가리킬 자리가 없어졌다. rev 4 가 방언을 1급으로 승격하며 rev 를
+ * 올렸던 것의 **역연산**이라 서술 정리가 아니라 잣대 변경이다. **아래 리터럴은 rev 6 과 바이트 동일**이다
+ * — 섹션 10종·`requiredRefs(AnyOf)` 는 한 글자도 안 바뀐다(동기 스크립트가 확인한다). 이 패키지에서
+ * 함께 내려간 것은 그 거처를 읽던 표면이다: `getPage`·`listPages`·`listMenus` 와 그 타입들.
+ * 남은 표기는 소스 하나 — `content/pages/*.json` 이 쓰는 참조 표기(`asset` 계열 문자열)이고,
+ * 어휘 표의 `assetId` 계열 키 이름은 그 시절 표기가 굳은 것이다(대응은 정본 `dialects.reference`).
  */
-declare const SECTION_CONTRACT_REV = 6;
-/** 업종 분류 — 콘솔 섹션 픽커의 그룹핑에 쓴다(테넌트 업종 필드는 아직 없다·memo102 §5). */
+declare const SECTION_CONTRACT_REV = 7;
+/** 업종 분류 — 어휘를 묶어 보여 줄 때의 그룹핑이지 사용 제한이 아니다(GENERAL 은 뷰티 사이트도 쓴다). */
 type SectionVertical = "BEAUTY" | "GENERAL";
 interface SectionSpec {
     readonly type: string;
@@ -994,7 +940,7 @@ interface SectionSpec {
      * 키 이름은 정본 그대로 **id 형**이다. 시드가 쓰는 참조형 키로 미리 바꿔 두지 않는 이유: 이 패키지는
      * 정본의 운반체이지 시드 문법의 번역기가 아니고, id↔참조 대응 규칙은 팩 게이트가 자기 자리에서 안다.
      *
-     * **필수성의 집행 지점은 팩/시드뿐이다** — 런타임은 그대로 관용이다(렌더러 스킵·콘솔 raw 편집 허용).
+     * **필수성의 집행 지점은 팩/시드뿐이다** — 런타임은 그대로 관용이다(렌더러가 그 섹션만 스킵한다).
      */
     readonly requiredRefs: readonly string[];
     /**
@@ -1013,8 +959,8 @@ interface SectionSpec {
     readonly requiredRefsAnyOf: readonly (readonly string[])[];
 }
 /**
- * 아는 섹션 전량(rev 6 기준 **10종**). **순서는 콘솔 픽커의 노출 순서**(관행 아크: 주목→가치→신뢰→행동).
- * 값 추가는 백엔드 스펙을 먼저 고친 뒤 여기로 옮긴다.
+ * 아는 섹션 전량(rev 7 기준 **10종** — rev 6 과 동일). **순서는 관행 아크**(주목→가치→신뢰→행동)이고,
+ * 어휘를 목록으로 보여 주는 자리는 이 순서를 그대로 쓰면 된다. 값 추가는 백엔드 스펙을 먼저 고친 뒤 여기로 옮긴다.
  *
  * `requiredRefs` 는 빈 배열이라도 **반드시 적는다**. 생략을 허용하면 동기 스크립트의 리터럴 정규식이
  * 그 항목을 통째로 못 읽고 "client 누락"으로 시끄럽게 죽는 대신, 오타 하나가 게이트를 조용히 끄는
@@ -1083,11 +1029,77 @@ declare const SECTION_CONTRACT: readonly [{
 }];
 /** 지금 렌더러가 아는 섹션 타입. 이 밖의 값이 와도 정상이다(스킵). */
 type KnownSectionType = (typeof SECTION_CONTRACT)[number]["type"];
-/** 업종별 필터 — 콘솔 픽커 그룹핑용. */
+/** 업종별 필터 — 어휘를 업종으로 묶어 볼 때 쓴다. */
 declare function sectionsOfVertical(vertical: SectionVertical): readonly SectionSpec[];
 
 declare function safeLinkUrl(raw: string | null | undefined): string;
 
+/**
+ * `X-Forwarded-For` 에서 **원 방문자 IP** 를 뽑는다. 백엔드 `ClientUtils.resolveClientIp` 의 **계약 거울**이다
+ * (같은 입력에 같은 값 — 테스트 벡터를 백엔드에서 그대로 이식해 드리프트를 막는다).
+ *
+ * ```ts
+ * // route handler 안
+ * import {visitorIp} from "@zalkera/client";
+ * const ip = visitorIp(req.headers);              // 프록시 1단(기본)
+ * await zalkera.submitInquiry(input, {clientIp: ip});
+ * ```
+ *
+ * ## 왜 이 함수가 있는가 — `xff.split(",")[0]` 는 위조된다
+ *
+ * `X-Forwarded-For` 는 **각 프록시가 자기가 받은 연결의 IP 를 오른쪽에 append** 하는 헤더다. 방문자가
+ * 요청에 `X-Forwarded-For: 9.9.9.9` 를 손으로 실으면 프록시는 그 뒤에 진짜 IP 를 붙이므로 헤더는
+ * `9.9.9.9, <진짜IP>` 가 된다 — **첫 엔트리는 공격자가 쓴 문자열**이다. 첫 홉을 채택하는 코드는 그래서
+ * 레이트리밋이 한 줄로 우회되고(요청마다 IP 를 바꾸면 버킷이 매번 새로 생긴다) IP 기록이 오염된다.
+ *
+ * 옳은 채택 지점은 **우리가 통제하는 프록시들이 붙인 블록의 가장 바깥(왼쪽) 엔트리** = 그 방문자가 우리
+ * 최외곽 프록시에 연결할 때 쓴 IP 다. 인덱스로는 `길이 - 신뢰홉수`.
+ *
+ * ## 보장 경계 — **여기까지만 참이다**
+ *
+ * 이 함수는 "부르기만 하면 안전"을 팔지 않는다. 파는 것은 **"선언한 홉 수가 참인 만큼 안전"** 이다.
+ * 자유 변수는 정수 하나([VisitorIpOptions.trustedHops])이고, 그 값이 틀리면 결과도 틀린다:
+ *
+ * | 선언 vs 실제 | 채택되는 값 | 결과 | 드러남 |
+ * |---|---|---|---|
+ * | 선언 **<** 실제(과소) | 안쪽 인프라 IP(CDN 엣지 등) | 방문자 전원이 한 IP 로 뭉침 → 429 폭주 | **가시** — 즉시 눈에 밟힌다 |
+ * | 선언 **=** 실제 | 방문자 IP | 정상 | — |
+ * | 선언 **>** 실제(과대) | **공격자가 넣은 임의 엔트리** | 위조 관통 | **비가시 — 조용히 뚫린다** |
+ *
+ * 그래서 규율은 하나다: **선언은 실제 이하로만.** 기본값 1 은 "항상 안전"이 아니라 **"위험한 방향으로는
+ * 기본값이 데려가지 않는"** 값이다 — 과대 선언에는 당신이 직접 큰 수를 적어야만 도달한다.
+ *
+ * **지원하지 않는 배포**: 리버스 프록시 **0단 직노출**(Node 를 인터넷에 직접 붙인 형태). 거기서는
+ * `X-Forwarded-For` **전체가** 방문자가 쓴 값이라 어떤 홉 수를 넣어도 이 함수는 위조를 돌려준다.
+ * 그 배포에서는 이 함수를 쓰지 말고 소켓 IP 를 플랫폼 수단으로 직접 얻어라 — 이 함수는 그 경우를
+ * 흡수하는 척하지 않는다.
+ *
+ * **우리가 모르는 것**: 당신의 프록시 단 수. 그래서 묻는다(옵션·env). 자동 감지는 **하지 않는다** —
+ * 결정적 신호가 없고(`CF-Connecting-IP` 존재도 신호가 못 된다: CF 밖에서 위조 가능), 추정은 과대 선언과
+ * 같은 위험이다. `x-real-ip` 폴백도 **하지 않는다** — 세우는 주체가 프록시마다 다르고 안 세우면 위조 자유다.
+ *
+ * **잘커라가 서빙하는 사이트라면** 이 값을 고민할 필요가 없다. 서빙 프록시가 방문자 IP **단일 엔트리**로
+ * `X-Forwarded-For` 를 재작성하므로 "신뢰 홉 = 1" 이 구성상 참이고, 그것이 이 함수의 기본값이다.
+ *
+ * @param headers `Headers` 또는 `NextRequest.headers` — `get(name)` 하나만 쓴다.
+ * @param options 홉 수 명시. 우선순위: 명시 > env `ZALKERA_TRUSTED_PROXY_HOPS` > 기본 1.
+ * @returns 원 방문자 IP. 정할 수 없으면 `undefined`(문자열 `"unknown"` 을 지어내지 않는다) —
+ *          그대로 `RequestContext.clientIp` 에 넣으면 되고, 클라이언트가 헤더를 생략한다.
+ */
+declare function visitorIp(headers: HeaderReader, options?: VisitorIpOptions): string | undefined;
+/** `get(name)` 만 요구한다 — `Headers`·`NextRequest.headers`·직접 만든 객체가 전부 들어맞는다. */
+interface HeaderReader {
+    get(name: string): string | null;
+}
+interface VisitorIpOptions {
+    /**
+     * 우리가(=당신이) 통제해 `X-Forwarded-For` 를 append 하는 프록시 **단 수**. 기본 1.
+     * 예: nginx 하나=1 · CDN+로드밸런서=2. **실제보다 크게 적지 마라** — 위 표의 '과대' 행이 조용한 구멍이다.
+     * `0` 이하를 주면 XFF 를 신뢰하지 않겠다는 뜻이라 항상 `undefined` 를 돌려준다.
+     */
+    trustedHops?: number;
+}
+
 /**
  * 섹션 config 파싱 — **절대 throw 하지 않는다.**
  *
@@ -1105,12 +1117,13 @@ declare function safeLinkUrl(raw: string | null | undefined): string;
  */
 declare function parseConfig<T>(config: string | null): T | null;
 /**
- * config 를 **거처와 무관하게** 읽는다 — 문자열이면 파싱하고, 이미 객체면 그대로 본다(rev 4).
+ * config 를 **입력 형태와 무관하게** 읽는다 — 문자열이면 파싱하고, 이미 객체면 그대로 본다(rev 4).
  *
- * 거처가 둘이 됐다: DB(`page_section.config` — JSON **문자열**)와 소스(`content/pages/*.json` 의
- * `sections[].config` — **객체**). 문자열인 것은 컬럼 저장 잔재이지 계약이 아니라(어휘 계약 rev 4
- * `dialects`), 소비자가 두 갈래로 갈리면 섹션 컴포넌트가 두 벌이 된다 — 이 패키지가 사본을 안 만드는
- * 이유 그대로다. 그래서 입구를 하나로 좁힌다.
+ * 계약이 말하는 config 는 **객체**다(`content/pages/*.json` 의 `sections[].config`). 문자열도 받는 이유는
+ * 둘이다: ⑴ 손으로 고치는 파일이라 config 를 통째 문자열로 적어 넣는 일이 실제로 있고 ⑵ 종전의 다른
+ * 거처(DB 컬럼)가 문자열을 줬다 — 그 거처는 rev 7 에서 사라졌지만(memo144) 관용은 append-only 로 남긴다.
+ * 소비자가 두 갈래로 갈리면 섹션 컴포넌트가 두 벌이 되고, 그것이 이 패키지가 사본을 안 만드는 이유
+ * 그대로다. 그래서 입구를 하나로 좁힌다.
  *
  * [parseConfig] 와 같은 계약: **절대 throw 하지 않고**, 객체가 아니면 `null`(배열도 null — 섹션 config
  * 는 객체다). 기존 `parseConfig` 는 그대로 둔다(append-only).
@@ -1179,4 +1192,4 @@ interface ParsedTheme {
 }
 declare function parseThemeColors(raw: string | null | undefined): ParsedTheme;
 
-export { type ApiErrorBody, type AuthTokens, type AvailabilityParams, type AvailabilitySlot, type Booking, type BookingStatus, type BusinessType, type Cart, type CartLine, type Category, type CheckoutInput, type ConsentInput, type ConsentStatus, type ConsentType, type CreateBookingInput, type CreateReviewInput, type CustomerSummary, type InquiryCreated, type InquiryInput, type KnownSectionType, type LeadCreated, type LeadInput, type LeadTracking, type ListPagesParams, type ListPostsParams, type ListProductsParams, type ListReviewsParams, type MediaUrl, type Menu, type MenuPosition, type OrderAccess, type OrderDetail, type OrderHistoryEntry, type OrderItemLine, type OrderStatus, type OrderSummary, type PageContent, type PageSection, type PageSummary, type Paginated, type ParsedTheme, type PaymentSession, type PostDetail, type PostSummary, type ProductCategory, type ProductDetail, type ProductSummary, type ProductType, type ProductVariant, type RatingSummary, type ReadOptions, type RequestContext, type Review, SECTION_CONTRACT, SECTION_CONTRACT_REV, type SectionSpec, type SectionVertical, type ShipToInput, type ShipmentEvent, type ShipmentInfo, type ShipmentStatus, type ShopSession, type SiteConfig, type SocialLoginInput, type SocialProvider, type ValidationError, type ZalkeraClient, type ZalkeraClientOptions, ZalkeraError, asHandle, asHandleArray, asId, asIdArray, asObjectArray, asString, assetPath, createZalkeraClient, mediaSrc, parseConfig, parseThemeColors, readConfig, safeLinkUrl, sectionsOfVertical };
+export { type ApiErrorBody, type AuthTokens, type AvailabilityParams, type AvailabilitySlot, type Booking, type BookingStatus, type BusinessType, type Cart, type CartLine, type Category, type CheckoutInput, type ConsentInput, type ConsentStatus, type ConsentType, type CreateBookingInput, type CreateReviewInput, type CustomerSummary, type HeaderReader, type InquiryCreated, type InquiryInput, type KnownSectionType, type LeadCreated, type LeadInput, type LeadTracking, type ListPostsParams, type ListProductsParams, type ListReviewsParams, type MediaUrl, type MenuPosition, type OrderAccess, type OrderDetail, type OrderHistoryEntry, type OrderItemLine, type OrderStatus, type OrderSummary, type Paginated, type ParsedTheme, type PaymentSession, type PostDetail, type PostSummary, type ProductCategory, type ProductDetail, type ProductSummary, type ProductType, type ProductVariant, type RatingSummary, type ReadOptions, type RequestContext, type Review, SECTION_CONTRACT, SECTION_CONTRACT_REV, type SectionSpec, type SectionVertical, type ShipToInput, type ShipmentEvent, type ShipmentInfo, type ShipmentStatus, type ShopSession, type SiteConfig, type SocialLoginInput, type SocialProvider, type ValidationError, type VisitorIpOptions, type ZalkeraClient, type ZalkeraClientOptions, ZalkeraError, asHandle, asHandleArray, asId, asIdArray, asObjectArray, asString, assetPath, createZalkeraClient, mediaSrc, parseConfig, parseThemeColors, readConfig, safeLinkUrl, sectionsOfVertical, visitorIp };

package/dist/index.js

@@ -23,7 +23,13 @@ var ZalkeraError = class _ZalkeraError extends Error {
     this.validationErrors = options.validationErrors ?? [];
     this.body = options.body ?? null;
   }
-  /** IP 레이트리밋(429) — 문의 폼에서 "잠시 후 다시" 를 띄울 때 쓴다. */
+  /**
+   * 레이트리밋(429) — "잠시 후 다시" 를 띄울 때 쓴다.
+   *
+   * 두 갈래다: ⑴ 문의·리드 폼 남발(IP 축) ⑵ **게스트 주문 인가 실패 누적** — 주문번호+연락처로
+   * 여는 주문 조회·취소·구매확정·배송조회·결제세션은 연락처 대입을 막으려고 실패를 센다.
+   * 정상 조회는 세지 않으므로, 이 코드가 뜨면 연락처를 여러 번 틀렸거나 같은 주문에 시도가 몰린 것이다.
+   */
   get isRateLimited() {
     return this.status === 429;
   }
@@ -100,7 +106,10 @@ function createZalkeraClient(options) {
     };
     if (options.secretKey) headers["X-Storefront-Key"] = options.secretKey;
     if (init?.body != null) headers["Content-Type"] = "application/json";
-    if (init?.context?.clientIp) headers["X-Forwarded-For"] = init.context.clientIp;
+    if (init?.context?.clientIp) {
+      headers["X-Zalkera-Client-Ip"] = init.context.clientIp;
+      headers["X-Forwarded-For"] = init.context.clientIp;
+    }
     if (init?.bearer) headers["Authorization"] = `Bearer ${init.bearer}`;
     if (init?.cartSession) headers["X-Cart-Session"] = init.cartSession;
     if (init?.idempotencyKey) headers["Idempotency-Key"] = init.idempotencyKey;
@@ -184,12 +193,6 @@ function createZalkeraClient(options) {
       method: "POST",
       context
     }),
-    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/${seg(id)}/url`),
     submitInquiry: (input, context) => request("/public/inquiries", {
       method: "POST",
@@ -289,7 +292,8 @@ function accessInit(access, extra) {
   return {
     ...extra,
     bearer: access.accessToken,
-    query: access.phone ? { phone: access.phone } : void 0
+    query: access.phone ? { phone: access.phone } : void 0,
+    context: access.context
   };
 }
 function isRedirectResponse(response) {
@@ -304,7 +308,7 @@ function safeJsonParse(text) {
 }
 
 // src/sections.ts
-var SECTION_CONTRACT_REV = 6;
+var SECTION_CONTRACT_REV = 7;
 var SECTION_CONTRACT = [
   // 뷰티(memo47) — 조회형 둘(SERVICE_MENU·BOOKING_CTA)은 rev 6 에서 삭제됐다(위 KDoc).
   // 시술 목록의 ItemList 는 사라진 것이 아니라 거처가 바뀌었다: `/products` 라우트와 소스가 조합하는
@@ -339,6 +343,32 @@ function safeLinkUrl(raw) {
   }
 }
 
+// src/visitorIp.ts
+function visitorIp(headers, options) {
+  const hops = options?.trustedHops ?? hopsFromEnv() ?? DEFAULT_TRUSTED_HOPS;
+  if (hops <= 0) return void 0;
+  const raw = headers?.get?.("x-forwarded-for");
+  if (raw == null || raw.trim() === "") return void 0;
+  const parts = raw.split(",").map((part) => part.trim()).filter((part) => part !== "");
+  if (parts.length === 0) return void 0;
+  const index = Math.min(Math.max(parts.length - hops, 0), parts.length - 1);
+  return parts[index] || void 0;
+}
+var DEFAULT_TRUSTED_HOPS = 1;
+var HOPS_ENV = "ZALKERA_TRUSTED_PROXY_HOPS";
+var envWarned = false;
+function hopsFromEnv() {
+  const raw = typeof process !== "undefined" ? process.env?.[HOPS_ENV] : void 0;
+  if (raw == null || raw.trim() === "") return void 0;
+  const parsed = Number(raw);
+  if (Number.isInteger(parsed)) return parsed;
+  if (!envWarned) {
+    envWarned = true;
+    console.warn(`@zalkera/client: ${HOPS_ENV}="${raw}" \uB294 \uC815\uC218\uAC00 \uC544\uB2D9\uB2C8\uB2E4 \u2014 \uAE30\uBCF8\uAC12 ${DEFAULT_TRUSTED_HOPS} \uB85C \uC9C4\uD589\uD569\uB2C8\uB2E4.`);
+  }
+  return void 0;
+}
+
 // src/sectionConfig.ts
 function parseConfig(config) {
   if (!config) return null;
@@ -461,6 +491,6 @@ function toRgb(hex) {
   return [parseInt(h.slice(0, 2), 16), parseInt(h.slice(2, 4), 16), parseInt(h.slice(4, 6), 16)];
 }
 
-export { SECTION_CONTRACT, SECTION_CONTRACT_REV, ZalkeraError, asHandle, asHandleArray, asId, asIdArray, asObjectArray, asString, assetPath, createZalkeraClient, mediaSrc, parseConfig, parseThemeColors, readConfig, safeLinkUrl, sectionsOfVertical };
+export { SECTION_CONTRACT, SECTION_CONTRACT_REV, ZalkeraError, asHandle, asHandleArray, asId, asIdArray, asObjectArray, asString, assetPath, createZalkeraClient, mediaSrc, parseConfig, parseThemeColors, readConfig, safeLinkUrl, sectionsOfVertical, visitorIp };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map