@zalkera/client 0.11.0 → 0.13.0

package/lib/site-crawl.mjs

@@ -0,0 +1,227 @@
+/**
+ * 개시된 사이트를 훑는 최소 크롤러 — `snapshot-preview.mjs`(memo116 §3)와
+ * `check-aeo-surfaces.mjs`(memo119 T5)가 **같은 사본**을 쓴다.
+ *
+ * 원래 이 코드는 snapshot-preview 안에 살았다. 보장 검사기가 "산출물을 크롤해 판정한다"(memo119 오너
+ * 전제 C)를 구현하려면 같은 훑기가 필요한데, 복사하면 두 크롤러가 조용히 갈라진다 — 한쪽이 라우트 분류를
+ * 고치고 다른 쪽이 안 고치면 "미리보기에는 나오는데 검사기는 못 보는 페이지"가 생긴다. 그래서 옮겼다.
+ *
+ * ── 외부 의존 0 ────────────────────────────────────────────────────────────
+ * 이 레포의 팩 스크립트가 zip 을 손으로 쓰는 것과 같은 규율이다. HTML 은 정규식 태그 스캐너로,
+ * 다운로드는 Node 내장 `fetch` 로 처리한다. 상대하는 마크업이 **우리가 만든 것**이라(임의 웹이 아니다)
+ * 파서를 들일 만큼의 다양성이 없다.
+ */
+
+// ── HTML 태그 스캐너 ─────────────────────────────────────────────────────────
+
+export const TAG_RE = /<([a-zA-Z][-\w:]*)((?:\s+[-\w:@.]+(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s"'=<>`]+))?)*)\s*(\/?)>/g;
+const ATTR_RE = /([-\w:@.]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/g;
+export const DROP = Symbol("drop-element");
+
+export function parseAttrs(text) {
+    const attrs = [];
+    if (!text) return attrs;
+    ATTR_RE.lastIndex = 0;
+    let m;
+    while ((m = ATTR_RE.exec(text)) !== null) {
+        attrs.push([m[1], m[2] ?? m[3] ?? m[4] ?? null]);
+    }
+    return attrs;
+}
+
+export const attrOf = (attrs, name) => {
+    const hit = attrs.find(([k]) => k.toLowerCase() === name);
+    return hit ? hit[1] : undefined;
+};
+
+/**
+ * `parseAttrs` 는 원문 조각을 **이스케이프된 그대로** 돌려준다. 여기서 `&` 를 다시 인코딩하면
+ * `&amp;` → `&amp;amp;` 가 되어 화면에 `&amp;` 가 그대로 보인다(심의 실측 — alt 텍스트가 깨졌다).
+ * 그래서 값은 손대지 않고, 따옴표만 원문에 없던 경우에 대비해 감싼다.
+ */
+export function serializeAttrs(attrs) {
+    return attrs.map(([k, v]) => (v === null ? ` ${k}` : ` ${k}="${String(v).replace(/"/g, "&quot;")}"`)).join("");
+}
+
+/**
+ * 태그 단위 변환. `transform` 이 [DROP] 을 돌려주면 그 **여는 태그만** 지운다 — 대상은 `<meta>`·`<link>`
+ * 같은 void 요소뿐이라 내용은 애초에 없다.
+ */
+export function rewriteTags(html, transform) {
+    return html.replace(TAG_RE, (full, name, attrText, selfClose) => {
+        const attrs = parseAttrs(attrText);
+        const out = transform(name.toLowerCase(), attrs);
+        if (out === DROP) return "";
+        if (!out) return full;
+        return `<${name}${serializeAttrs(out)}${selfClose ? " /" : ""}>`;
+    });
+}
+
+/** HTML 엔티티만 푼다 — 속성값에서 URL 을 꺼낼 때 필요한 최소셋. */
+export const unescapeAttr = (v) =>
+    v.replace(/&amp;/g, "&").replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&lt;/g, "<").replace(/&gt;/g, ">");
+
+// ── 라우트 정책 ──────────────────────────────────────────────────────────────
+
+export const segmentsOf = (path) => path.split("/").filter(Boolean);
+
+/**
+ * 정적으로 성립할 수 없는 기능 라우트. 세션·쓰기·결제다.
+ * validator 의 `SEO_EXCLUDE_SEGMENTS`(ISR 게이트 제외 목록)와 같은 어휘를 쓴다 — 그쪽이
+ * "정당하게 동적인 인터랙티브 경로"로 이미 판정해 둔 집합이고, 둘이 갈리면 한쪽이 틀린 것이다.
+ */
+export const FUNCTIONAL_SEGMENTS = new Set([
+    "api", "cart", "checkout", "mypage", "account", "login", "auth", "orders", "payment",
+]);
+
+/**
+ * 테넌트 **식별정보 표시면**. 미리보기 스냅샷은 이걸 크롤하지 않는다(가릴 것만 많다).
+ * 보장 검사기는 다르다 — 아무것도 공개하지 않고 판정만 하므로 여기를 훑어도 유출 표면이 없다.
+ * 그래서 이 집합은 상수가 아니라 **호출자가 고르는 값**이다.
+ */
+export const IDENTITY_ROUTES = new Set(["/policies", "/contact"]);
+
+/** 페이지가 아닌 기계용 파일. */
+export const MACHINE_FILES = new Set(["/robots.txt", "/sitemap.xml", "/favicon.ico"]);
+
+/** 이 확장자는 페이지가 아니라 자산이다(경로만 보고 판정할 때). */
+export const ASSET_EXT = new Set([
+    ".css", ".js", ".mjs", ".map", ".png", ".jpg", ".jpeg", ".webp", ".gif", ".svg", ".avif",
+    ".ico", ".woff", ".woff2", ".ttf", ".otf", ".mp4", ".webm", ".json", ".xml", ".txt",
+]);
+
+/**
+ * URL 하나를 분류하는 함수를 만든다. `origin` 은 크롤 대상 오리진, `skipRoutes` 는 페이지지만
+ * 훑지 않을 경로 집합(미리보기=식별정보 라우트, 검사기=빈 집합).
+ */
+export function makeClassifier({origin, skipRoutes = IDENTITY_ROUTES}) {
+    return function classify(rawUrl, fromPath) {
+        let u;
+        try {
+            u = new URL(unescapeAttr(rawUrl), origin + fromPath);
+        } catch {
+            return {kind: "opaque"};
+        }
+        if (u.protocol !== "http:" && u.protocol !== "https:") return {kind: "opaque"}; // mailto:·tel:·data:
+        if (u.origin !== origin) return {kind: "external", url: u};
+        const path = u.pathname;
+        if (path.startsWith("/_next/") || path.startsWith("/media/")) return {kind: "asset", url: u};
+        if (ASSET_EXT.has(extnameOf(path))) return {kind: "asset", url: u};
+        if (MACHINE_FILES.has(path)) return {kind: "blocked", url: u};
+        const segs = segmentsOf(path);
+        if (segs.some((s) => FUNCTIONAL_SEGMENTS.has(s))) return {kind: "blocked", url: u};
+        if (skipRoutes.has(path.replace(/\/+$/, "") || "/")) return {kind: "blocked", url: u};
+        return {kind: "page", path: path.replace(/\/+$/, "") || "/"};
+    };
+}
+
+/** `node:path` 의 extname 과 같되 소문자로. 경로 문자열만 상대하므로 의존을 안 들인다. */
+function extnameOf(path) {
+    const base = path.slice(path.lastIndexOf("/") + 1);
+    const dot = base.lastIndexOf(".");
+    return dot <= 0 ? "" : base.slice(dot).toLowerCase();
+}
+
+// ── 링크 수집 ────────────────────────────────────────────────────────────────
+
+const splitSrcset = (v) => (v ? v.split(",").map((p) => p.trim().split(/\s+/)[0]).filter(Boolean) : []);
+
+/**
+ * 페이지 HTML 에서 나가는 링크·자산을 수집한다(변형 없음 — 1차 통과).
+ * `sink` 는 blocked·external 을 받는 선택 콜백(미리보기 리포트가 쓴다).
+ */
+export function collectLinks(html, fromPath, classify, sink = {}) {
+    const links = new Set();
+    const assetUrls = new Set();
+    const absOrNull = (raw) => {
+        if (!raw) return null;
+        const c = classify(raw, fromPath);
+        return c.kind === "asset" ? c.url.toString() : null;
+    };
+    rewriteTags(html, (tag, attrs) => {
+        const push = (raw) => {
+            if (!raw) return;
+            const c = classify(raw, fromPath);
+            if (c.kind === "page") links.add(c.path);
+            else if (c.kind === "asset") assetUrls.add(c.url.toString());
+            else if (c.kind === "blocked") sink.blocked?.(c.url.pathname);
+            else if (c.kind === "external") sink.external?.(c.url.origin);
+        };
+        if (tag === "a") push(attrOf(attrs, "href"));
+        if (tag === "link") {
+            const rel = (attrOf(attrs, "rel") ?? "").toLowerCase();
+            if (rel.includes("stylesheet") || rel.includes("icon")) assetUrls.add(absOrNull(attrOf(attrs, "href")));
+        }
+        if (tag === "img" || tag === "source" || tag === "video" || tag === "audio") {
+            const src = absOrNull(attrOf(attrs, "src"));
+            if (src) assetUrls.add(src);
+            for (const s of splitSrcset(attrOf(attrs, "srcset"))) {
+                const abs = absOrNull(s);
+                if (abs) assetUrls.add(abs);
+            }
+        }
+        return null;
+    });
+    assetUrls.delete(null);
+    return {links, assetUrls};
+}
+
+// ── 크롤 ─────────────────────────────────────────────────────────────────────
+
+/**
+ * 링크를 따라 페이지 HTML 을 모은다. **JS 를 실행하지 않는다** — 그것이 요점이다: 여기서 보이는
+ * 것이 크롤러·답변 엔진이 실제로 받는 것이고, 하이드레이션 뒤에만 나타나는 내용은 보장이 아니다.
+ *
+ * 반환: `{pages: Map<routePath, html>, assetUrls: Set, fetchFailures: string[], blocked: Set, external: Set}`
+ */
+export async function crawlPages({
+    origin,
+    entryPath = "/",
+    extraRoutes = [],
+    maxPages = 60,
+    classify,
+    userAgent = "zalkera-crawler",
+    onPage = null,
+}) {
+    const pages = new Map();
+    const assetUrls = new Set();
+    const fetchFailures = [];
+    const blocked = new Set();
+    const external = new Set();
+    const sink = {blocked: (p) => blocked.add(p), external: (o) => external.add(o)};
+
+    const queue = [entryPath, ...extraRoutes.map((r) => (r.startsWith("/") ? r : `/${r}`))];
+    const seen = new Set();
+
+    while (queue.length > 0 && pages.size < maxPages) {
+        const path = queue.shift();
+        if (seen.has(path)) continue;
+        seen.add(path);
+
+        const url = origin + (path === "/" ? "/" : path);
+        let res;
+        try {
+            res = await fetch(url, {headers: {"user-agent": userAgent}});
+        } catch (e) {
+            fetchFailures.push(`${url} — ${e.message}`);
+            continue;
+        }
+        if (!res.ok) {
+            fetchFailures.push(`${url} — HTTP ${res.status}`);
+            continue;
+        }
+        if (!(res.headers.get("content-type") ?? "").includes("html")) {
+            fetchFailures.push(`${url} — HTML 이 아닙니다(${res.headers.get("content-type")})`);
+            continue;
+        }
+        const html = await res.text();
+        pages.set(path, html);
+        onPage?.(path);
+
+        const collected = collectLinks(html, path, classify, sink);
+        for (const l of collected.links) if (!seen.has(l)) queue.push(l);
+        for (const a of collected.assetUrls) assetUrls.add(a);
+    }
+
+    return {pages, assetUrls, fetchFailures, blocked, external};
+}

package/llms.txt

@@ -137,6 +137,8 @@ await zalkera.submitInquiry(input, { clientIp: ip });
 
 - `safeLinkUrl(raw)` → `string` — **모든 `href` 는 이걸 태운다.** 콘솔 입력이라 `javascript:` 가 들어올 수 있다(저장형 XSS).
 - `parseConfig<T>(config)` → `T | null` — 섹션 `config` JSON 파싱. **절대 throw 하지 않는다**(실패 시 null).
+- `readConfig<T>(config)` → `T | null` — 같은 계약인데 **문자열이든 객체든** 받는다. 섹션 config 의 거처가 둘이라
+  (백엔드 `page_section.config` = JSON 문자열 · 레포 콘텐츠 파일 = 객체) 소비자를 두 벌로 만들지 않으려는 입구다.
 - `asString(v)` / `asId(v)` — 형이 안 맞으면 `undefined`.
 - `asIdArray(v)` / `asObjectArray(v)` — **빈 배열**로 강하한다(undefined 아님).
   빈 배열은 truthy 라 `if (items)` 로 결측을 판별하면 안 된다 — `items.length` 을 봐라.
@@ -144,6 +146,10 @@ await zalkera.submitInquiry(input, { clientIp: ip });
 - `mediaSrc(assetId)` → `/media/{id}` **경로 문자열**. 이미지는 전부 이걸 통한다.
   전제: 프로젝트에 `app/media/[id]/route.ts` 프록시 라우트가 있어야 한다(템플릿에 있다).
   이 헬퍼는 경로만 만든다 — 라우트를 안 만들면 이미지가 404 다.
+- `asHandle(v)` / `asHandleArray(v)` / `assetPath(v)` — **참조 방언**(계약 `contractRev` 4 의 `dialects`)을 읽는다.
+  숫자 id 를 못 쓰는 자리에서 상품은 `handle`(= `ProductSummary.slug`), 에셋은 레포 `public/` **루트 절대 경로**로
+  가리킨다. `assetPath` 는 루트 절대 경로만 통과시킨다(스킴·`//`·`..`·역슬래시 → `undefined`).
+  `asHandleArray` 는 **배열 순서를 보존**한다 — 그 순서가 노출 순서의 원장이다.
 - `SECTION_CONTRACT` / `SECTION_CONTRACT_REV` / `sectionsOfVertical(vertical)` — 아는 섹션 어휘의 코드 표현(§9).
   타입·키를 **지어내지 말고** 여기서 확인한다.
 - `parseThemeColors(raw)` → `ParsedTheme` — 테마 토큰 파서(§8). 화이트리스트라 임의 CSS 가 안 들어온다.
@@ -191,6 +197,20 @@ export default async function Products() {
 }
 ```
 
+### 4.1-a 카테고리 페이지 (RSC)
+```tsx
+// app/c/[slug]/page.tsx
+const categories = await zalkera.listProductCategories();
+const category = categories.find(c => c.slug === slug);
+if (!category) notFound();                       // 카테고리 부재만 404 다
+const page = await zalkera.listProducts({ categoryId: category.id, size: 24 });
+```
+- **좁히는 축은 `categoryId`(숫자)** 다 — slug 가 아니다. slug 로 카테고리를 찾고 그 id 로 상품을 좁힌다.
+- 없는 `categoryId` 는 **빈 목록**이지 404 가 아니다. 목록 API 는 "그 카테고리가 있느냐"를 답하지 않는다 —
+  404 판단은 카테고리를 못 찾은 라우트가 한다(위 `notFound()`).
+- 목록 조회 실패는 삼켜 빈 카테고리로 강하해도 되지만, **카테고리 목록 조회 실패를 404 로 바꾸지 마라** —
+  백엔드 장애를 "그런 카테고리 없음"으로 말하면 크롤러가 그 오답을 캐시한다.
+
 ### 4.2 상품 상세 + 장바구니 담기
 ```tsx
 // app/products/[slug]/page.tsx (RSC) — 조회는 공개
@@ -409,13 +429,15 @@ if (booking.orderNo) {                  // status=PENDING
 
 **이 절의 규범은 기계로 잴 수 있다.** 이 패키지는 판정 잣대인 **보장표**를
 `@zalkera/client/contracts/aeo-surface-guarantees.json` 으로 함께 배송한다(정본은 잘커라 백엔드에 있고 이것은
-그 발행 산출물이다 — 내용이 갈라지지 않게 발행 전 기계가 대조한다). 스토어프론트 템플릿의
-`scripts/check-aeo-surfaces.mjs` 가 그 표를 읽어 **개시된 사이트를 크롤해** 판정하므로, 소스가 아니라
-산출물이 잣대다 — 어떤 스택으로 짰든 같은 조건이다:
+그 발행 산출물이다 — 내용이 갈라지지 않게 발행 전 기계가 대조한다). **검사기 자신도 이 패키지가 싣고
+온다**(bin `zalkera-aeo-check`) — 그 표를 읽어 **개시된 사이트를 크롤해** 판정하므로, 소스가 아니라
+산출물이 잣대다. 어떤 스택으로 짰든 같은 조건이다:
 
 ```bash
-# 템플릿에서 출발한 프로젝트(그 스크립트가 있는 곳)에서:
-npm run check:aeo -- https://개시된사이트 --category BOOKING   # 0=통과 · 1=미충족 · 2=실행 불가
+npx zalkera-aeo-check https://개시된사이트 --category BOOKING   # 0=통과 · 1=미충족 · 2=실행 불가
+npx zalkera-aeo-check https://개시된사이트 --site-wide-only     # 보장 주장이 없는 사이트(사이트 축만)
+# 템플릿에서 출발한 프로젝트라면 같은 검사기를 이렇게도 부른다:
+npm run check:aeo -- https://개시된사이트 --category BOOKING
 npm run check:aeo -- --print-guarantees                        # 잣대 해석만 확인(크롤 없음)
 ```
 

package/package.json

@@ -1,53 +1,60 @@
 {
-    "name": "@zalkera/client",
-    "version": "0.11.0",
-    "description": "zalkera 헤드리스 CMS 공개 API 클라이언트 (테넌트 사이트용)",
-    "license": "MIT",
-    "author": "Credium Co., Ltd.",
-    "type": "module",
-    "publishConfig": {
-        "access": "public"
+  "name": "@zalkera/client",
+  "version": "0.13.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",
+    "contracts",
+    "bin",
+    "lib"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "zalkera-aeo-check": "./bin/check-aeo-surfaces.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
     },
-    "keywords": [
-        "zalkera",
-        "headless",
-        "commerce",
-        "cms",
-        "api-client",
-        "sdk"
-    ],
-    "homepage": "https://zalkera.com",
-    "files": [
-        "dist",
-        "llms.txt",
-        "contracts"
-    ],
-    "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"
-        },
-        "./contracts/aeo-surface-guarantees.json": "./contracts/aeo-surface-guarantees.json"
-    },
-    "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"
-    }
+    "./contracts/aeo-surface-guarantees.json": "./contracts/aeo-surface-guarantees.json",
+    "./bin/check-aeo-surfaces.mjs": "./bin/check-aeo-surfaces.mjs",
+    "./lib/site-crawl.mjs": "./lib/site-crawl.mjs"
+  },
+  "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"
+  }
 }