daiso 1.0.8 → 1.0.10

package/README.md

@@ -7,7 +7,7 @@
 
 # Daiso MCP 및 Skill
 
-다이소(제품/매장/재고), 키 없는 통합 가격 후보 비교, 주변 음식점/카페, 롯데마트(매장/상품), GS25(매장/상품/재고), 세븐일레븐(상품/매장/재고/인기검색어/카탈로그), CU(매장/재고), 이마트24(매장/상품/재고), 올리브영(매장/재고), 메가박스(지점/영화/시간표/좌석), 롯데시네마(지점/영화/좌석), CGV(극장/영화/시간표) 조회 기능을 MCP, CLI, Codex Skill로 AI에 연결합니다.
+다이소(제품/매장/재고), 상품 가격 비교, 주변 음식점/카페, 주유소/유가, 개발자 요청 제출, 롯데마트(매장/상품), GS25(매장/상품/재고), 세븐일레븐(상품/매장/재고/인기검색어/카탈로그), CU(매장/재고), 이마트24(매장/상품/재고), 올리브영(매장/재고), 메가박스(지점/영화/시간표/좌석), 롯데시네마(지점/영화/좌석), CGV(극장/영화/시간표) 조회 기능을 MCP, CLI, Codex Skill로 AI에 연결합니다.
 
 <br>
 
@@ -15,7 +15,8 @@
 
 **ClawHub:** [clawhub.ai/hmmhmmhm/daiso-cli](https://clawhub.ai/hmmhmmhm/daiso-cli)
 
-한국 로컬 리테일과 영화관 조회를 MCP, CLI, Codex Skill로 연결하는 도구입니다.
+한국 로컬 리테일, 생활 정보, 영화관 조회를 MCP, CLI, Codex Skill로 연결하는 도구입니다.
+사용자는 별도 API 키를 준비하지 않고 바로 사용할 수 있습니다.
 
 <br>
 
@@ -35,10 +36,20 @@
       <td>네이버 지역 검색</td>
       <td>음식점, 카페, 디저트, 주변 장소</td>
     </tr>
+    <tr>
+      <td>교통</td>
+      <td>오피넷</td>
+      <td>전국 평균 유가, 최저가 주유소, 위치 기반 주유소, 주유소 상세정보</td>
+    </tr>
     <tr>
       <td>비교</td>
       <td>다이소, GS25, 세븐일레븐, 이마트24</td>
-      <td>새 외부 키 없는 상품 가격 후보 비교</td>
+      <td>같은 상품의 판매처별 가격 후보 비교</td>
+    </tr>
+    <tr>
+      <td>운영</td>
+      <td>Supabase</td>
+      <td>MCP 오류, 개선 요청, 신규 기능 요청 저장</td>
     </tr>
     <tr>
       <td>리테일</td>
@@ -70,11 +81,11 @@
 **[실시간 서비스 상태 보기](https://aka-page.betteruptime.com/)**
 
 <!-- WORKERS_INVOCATIONS_CHART:START -->
-<h3>Cloudflare Workers 호출량 (2026-03-01 ~ 2026-05-23, 84일)</h3>
+<h3>Cloudflare Workers 호출량 (2026-06-14 ~ 2026-07-13, 30일)</h3>
 
-<img src="./assets/analytics/workers-invocations.png?v=2026-05-23T15:44:29.609Z" alt="Cloudflare Workers 호출량 그래프 (2026-03-01 ~ 2026-05-23)" width="100%">
+<img src="./assets/analytics/workers-invocations.png?v=2026-07-13T16:10:36.883Z" alt="Cloudflare Workers 호출량 그래프 (2026-06-14 ~ 2026-07-13)" width="100%">
 
-<sub>기준 워커: <code>daiso-mcp</code> · 마지막 갱신: 2026-05-24 00:44 KST</sub>
+<sub>기준 워커: <code>daiso-mcp</code> · 마지막 갱신: 2026-07-14 01:10 KST</sub>
 
 <!-- WORKERS_INVOCATIONS_CHART:END -->
 
@@ -122,12 +133,24 @@ GS25 mcp로 강남 근처 매장과 오감자 재고 알려줘
 세븐일레븐 mcp로 인기 검색어와 카탈로그 요약 알려줘
 강남역 근처 카페 찾아줘
 성수동 근처 브런치 음식점 찾아줘
+강남역 근처 제일 싼 주유소 찾아줘
+오늘 전국 평균 휘발유 가격 알려줘
 메가박스 mcp로 강남점 영화와 잔여 좌석 알려줘
 롯데시네마 mcp로 월드타워 근처 지점과 상영 영화 알려줘
 롯데시네마 mcp로 월드타워 잔여 좌석 알려줘
 CGV mcp로 강남 상영 영화와 시간표 알려줘
 ```
 
+에이전트가 고르면 좋은 대표 흐름:
+
+- 가격 비교: `콜라 어디가 싸?` → `compare_products`
+- 주변 장소: `강남역 근처 카페 찾아줘` → `places_search_nearby`
+- 주유소/유가: `강남역 근처 제일 싼 주유소 찾아줘` → `opinet_search_stations_around`
+- 브랜드 명시 재고: `다이소 핫식스 재고 찾아줘` → 먼저 다이소에서 검색 후 결과 없을 때만 대안 제안
+- 편의점 재고: `GS25 강남 오감자 재고` → 상품 후보 확인 후 재고 조회
+- 영화 시간표: `오늘 강남 CGV 시간표` → KST 오늘 날짜로 극장 검색 후 시간표 조회
+- 개발자 요청: `올리브영 재고 도구가 계속 실패한다고 개발자에게 알려줘` → `submit_developer_request`
+
 <br>
 
 ### ![Claude](https://img.shields.io/badge/Claude-D4A27F?logo=anthropic&logoColor=white)
@@ -223,7 +246,7 @@ AI 앱 연동 없이 터미널에서 바로 확인할 수 있습니다.
 npx daiso products 수납박스 --json
 npx daiso places 강남역 --category cafe --limit 5 --json
 npx daiso gs25-inventory 오감자 --storeKeyword 강남 --storeLimit 5 --json
-npx daiso get /api/cgv/movies --playDate 20260520 --theaterCode 0056 --json
+npx daiso cgv-movies --playDate 20260520 --theaterCode 0056 --json
 ```
 
 <br>
@@ -263,8 +286,13 @@ npx daiso display-location 1034604 04515
 npx daiso compare 콜라 --limit 3
 npx daiso places 강남역 --category cafe --limit 5
 npx daiso places 성수동 --keyword 브런치 --limit 5
+npx daiso get /api/opinet/lowest --fuelCode B027 --areaCode 0113 --count 5 --json
+npx daiso get /api/opinet/average --json
 npx daiso cu-stores 강남
 npx daiso cu-inventory 과자 --storeKeyword 강남
+npx daiso cgv-theaters 강남 --limit 10
+npx daiso cgv-movies --playDate 20260307 --theaterCode 0056
+npx daiso cgv-timetable --playDate 20260307 --theaterCode 0056
 npx daiso lottemart-stores 잠실 --area 서울 --limit 10
 npx daiso lottemart-products 콜라 --storeName 강변점 --area 서울
 npx daiso emart24-stores 강남 --service24h true
@@ -275,10 +303,9 @@ npx daiso gs25-products 오감자 --limit 20
 npx daiso gs25-inventory 오감자 --storeKeyword 강남 --storeLimit 10
 npx daiso seveneleven-products 삼각김밥 --size 20
 npx daiso seveneleven-stores 안산 중앙역 --limit 10
-npx daiso get /api/seveneleven/inventory --keyword 핫식스 --storeKeyword 안산%20중앙역 --storeLimit 10
+npx daiso seveneleven-inventory 핫식스 --storeKeyword "안산 중앙역" --storeLimit 10
 npx daiso seveneleven-popwords --label home
 npx daiso seveneleven-catalog --includeIssues true --includeExhibition true --limit 10
-npx daiso get /api/cgv/movies --playDate 20260307 --theaterCode 0056
 
 # 원본 JSON 필요 시
 npx daiso products 수납박스 --json
@@ -294,6 +321,7 @@ npx daiso products 수납박스 --json
 - 명령 맵: `skills/daiso-cli/references/cli-command-map.md`
 - 기본 원칙: 쉘 실행이 가능한 환경에서는 CLI를 우선 사용하고, AI 앱 연결이 필요할 때는 MCP 서버 URL `https://mcp.aka.page`를 사용합니다.
 - 구조화 결과가 필요하면 스킬은 `npx daiso ... --json` 형태를 선택합니다.
+- 상황별 레시피는 `콜라 어디가 싸?`, `강남역 근처 카페`, `다이소 핫식스 재고`, `오늘 강남 CGV 시간표`처럼 실제 사용자 문장 기준으로 정리되어 있습니다.
 
 ### OpenAPI 스펙
 
@@ -311,9 +339,9 @@ MCP 도구 응답은 각 서비스의 원본 필드를 유지하면서, 클라
 - `standard.theaters`: 영화관 목록을 `code`, `name`, `address`, `distanceMeters`, `raw` 형태로 정규화합니다.
 - `standard.places`: 음식점/카페 같은 장소 목록을 `name`, `address`, `raw` 중심으로 정규화합니다.
 
-### 키 없는 통합 가격 후보 비교
+### 통합 상품 가격 비교
 
-새 외부 API 키 없이 기존 상품 검색을 묶어 가격 후보를 비교합니다.
+여러 리테일/편의점 상품 검색 결과를 묶어 같은 상품의 판매처별 가격 후보를 비교합니다.
 
 ```bash
 npx daiso compare 콜라 --limit 3 --json
@@ -327,6 +355,63 @@ GET /api/compare/products?keyword=콜라&limit=3
 
 지원 서비스는 `daiso`, `gs25`, `seveneleven`, `emart24`입니다. GS25처럼 상품 검색 응답에 가격이 없는 서비스는 후보에는 포함되지만 최저가 계산에서는 제외됩니다.
 
+### 오피넷 유가 정보
+
+한국석유공사 오피넷 유가정보 API로 전국 평균 유가, 지역별 최저가 주유소, 반경 내 주유소, 주유소 상세정보를 조회합니다.
+
+MCP 도구:
+
+```text
+opinet_get_average_prices
+opinet_get_lowest_price_stations
+opinet_search_stations_around
+opinet_get_station_detail
+```
+
+REST:
+
+```text
+GET /api/opinet/average
+GET /api/opinet/lowest?fuelCode=B027&areaCode=0113&count=5
+GET /api/opinet/stations/around?lat=37.4979&lng=127.0276&radiusMeters=3000&fuelCode=B027&sort=price
+GET /api/opinet/stations/around?location=강남역&radiusMeters=3000&fuelCode=B027&sort=price
+GET /api/opinet/stations/around?x=314681.8&y=544837&radiusMeters=3000&fuelCode=B027&sort=price
+GET /api/opinet/station?id=A0010207
+```
+
+오피넷 API 키는 `OPINET_API_KEY` 환경 변수 또는 Cloudflare Worker Secret으로 설정합니다. 키 발급은 오피넷 웹사이트의 `유가관련정보 > 유가정보 API > 인증키 발급`에서 진행합니다. 반경 검색은 `lat/lng`, `location`, KATEC `x/y`를 모두 지원하며, `location` 검색에는 `GOOGLE_MAPS_API_KEY`가 필요합니다.
+
+운영 제약 및 캐싱 정책:
+
+- 오피넷 무료 API는 한국석유공사 공공데이터 활용 가이드 기준 **1일 1,500 call** 한도를 기준으로 운영합니다.
+- 모든 오피넷 응답에는 `source: "한국석유공사 오피넷"`과 `fetchedAt`을 포함합니다.
+- Cloudflare Edge Cache로 동일 GET 요청의 원본 오피넷 호출을 줄입니다.
+- `GET /api/opinet/average`: 60분 캐시, 30분 stale-while-revalidate
+- `GET /api/opinet/lowest`: 30분 캐시, 10분 stale-while-revalidate
+- `GET /api/opinet/stations/around`: 20분 캐시, 5분 stale-while-revalidate
+- `GET /api/opinet/station`: 60분 캐시, 10분 stale-while-revalidate
+- `location` 키워드의 Google Geocoding 결과는 Worker 인스턴스 메모리에서 24시간 캐시합니다.
+- 호출 한도에 자주 도달하면 운영자가 담당 기관인 한국석유공사/오피넷에 문의해 추가 할당량 또는 별도 이용 조건을 협의할 예정입니다.
+
+### 개발자 요청 제출
+
+AI 에이전트가 MCP 기능 오류, 개선 요청, 신규 기능 요청, 문서 문제를 바로 개발자에게 전달할 수 있습니다. 요청은 Supabase `agent_requests` 테이블에 저장됩니다.
+
+MCP 도구:
+
+```text
+submit_developer_request
+```
+
+REST:
+
+```text
+POST /api/feedback/requests
+GET /api/feedback/requests?type=bug&title=제목&description=설명
+```
+
+로컬 실행이나 배포 환경에는 `SUPABASE_URL`, `SUPABASE_SERVICE_ROLE_KEY`를 설정하세요. 테이블 스키마는 [supabase-agent-requests.sql](./docs/supabase-agent-requests.sql)에 있습니다.
+
 ### 운영 헬스 체크
 
 공개 상태 페이지: **[Daiso MCP Status](https://aka-page.betteruptime.com/)**

package/dist/api/actionsProxy.js

@@ -96,6 +96,11 @@ export const ACTION_QUERY_DEFINITIONS = [
         summary: '음식점/카페 등 주변 장소 검색',
         targetPath: '/api/places/search',
     },
+    {
+        action: 'submitDeveloperRequest',
+        summary: '개발자 요청 제출',
+        targetPath: '/api/feedback/requests',
+    },
     {
         action: 'megaboxFindTheaters',
         summary: '메가박스 지점 검색',

package/dist/api/configStatus.js

@@ -15,6 +15,14 @@ export function buildConfigStatus(bindings) {
             configured: isConfigured(bindings?.NAVER_CLIENT_ID) && isConfigured(bindings?.NAVER_CLIENT_SECRET),
             usedBy: ['places'],
         },
+        opinetApiKey: {
+            configured: isConfigured(bindings?.OPINET_API_KEY),
+            usedBy: ['opinet'],
+        },
+        supabaseFeedback: {
+            configured: isConfigured(bindings?.SUPABASE_URL) && isConfigured(bindings?.SUPABASE_SERVICE_ROLE_KEY),
+            usedBy: ['feedback'],
+        },
         healthCheckSecret: {
             configured: isConfigured(bindings?.HEALTH_CHECK_SECRET),
             usedBy: ['health-checks'],

package/dist/api/feedbackHandlers.js

@@ -0,0 +1,60 @@
+import { errorResponse, successResponse } from './response.js';
+import { submitDeveloperRequest } from '../services/feedback/index.js';
+function getErrorMessage(error) {
+    return error instanceof Error ? error.message : '알 수 없는 오류가 발생했습니다.';
+}
+async function readJsonBody(c) {
+    if (c.req.method !== 'POST') {
+        return {};
+    }
+    return c.req.json().catch(() => ({}));
+}
+function queryInput(c) {
+    return {
+        type: c.req.query('type'),
+        severity: c.req.query('severity'),
+        title: c.req.query('title') || '',
+        description: c.req.query('description') || '',
+        service: c.req.query('service'),
+        toolName: c.req.query('toolName'),
+        reproduction: c.req.query('reproduction'),
+        expected: c.req.query('expected'),
+        actual: c.req.query('actual'),
+        source: c.req.query('source') || 'api',
+    };
+}
+function normalizeInput(raw) {
+    return {
+        type: typeof raw.type === 'string' ? raw.type : undefined,
+        severity: typeof raw.severity === 'string' ? raw.severity : undefined,
+        title: typeof raw.title === 'string' ? raw.title : '',
+        description: typeof raw.description === 'string' ? raw.description : '',
+        service: typeof raw.service === 'string' ? raw.service : undefined,
+        toolName: typeof raw.toolName === 'string' ? raw.toolName : undefined,
+        reproduction: typeof raw.reproduction === 'string' ? raw.reproduction : undefined,
+        expected: typeof raw.expected === 'string' ? raw.expected : undefined,
+        actual: typeof raw.actual === 'string' ? raw.actual : undefined,
+        source: typeof raw.source === 'string' ? raw.source : undefined,
+        userContext: raw.userContext,
+    };
+}
+export async function handleSubmitDeveloperRequest(c) {
+    try {
+        const body = await readJsonBody(c);
+        const input = normalizeInput(c.req.method === 'POST' ? body : queryInput(c));
+        if (!input.title.trim()) {
+            return errorResponse(c, 'MISSING_FEEDBACK_TITLE', 'title을 입력해주세요.', 400);
+        }
+        if (!input.description.trim()) {
+            return errorResponse(c, 'MISSING_FEEDBACK_DESCRIPTION', 'description을 입력해주세요.', 400);
+        }
+        const result = await submitDeveloperRequest(input, {
+            supabaseUrl: c.env?.SUPABASE_URL,
+            supabaseServiceRoleKey: c.env?.SUPABASE_SERVICE_ROLE_KEY,
+        });
+        return successResponse(c, result);
+    }
+    catch (error) {
+        return errorResponse(c, 'DEVELOPER_REQUEST_SUBMIT_FAILED', getErrorMessage(error), 500);
+    }
+}

package/dist/api/healthCheckDefinitions.js

@@ -0,0 +1,188 @@
+/**
+ * 서비스별 헬스 체크 정의
+ */
+export const GS25_CLOUDFRONT_403_PATTERNS = [
+    '403 Forbidden',
+    'The request could not be satisfied',
+    '403 ERROR',
+];
+export const EMART24_UPSTREAM_403_PATTERNS = [
+    '403 Forbidden',
+    '<title>403 Forbidden</title>',
+];
+export const CU_UPSTREAM_BLOCK_PATTERNS = [
+    '400 Bad Request',
+    'Request Blocked',
+];
+export const SEVENELEVEN_UPSTREAM_403_PATTERNS = [
+    '403 Forbidden',
+    '_Incapsula_Resource',
+    'NOINDEX, NOFOLLOW',
+];
+export const HEALTH_CHECKS = [
+    {
+        id: 'cli.contract',
+        service: 'cli',
+        target: 'api-contract',
+        mode: 'deep',
+        kind: 'cli-contract',
+        path: '/health',
+    },
+    {
+        id: 'daiso.products',
+        service: 'daiso',
+        target: 'products',
+        mode: 'quick',
+        path: '/api/daiso/products?q=%ED%85%8C%EC%9D%B4%ED%94%84&pageSize=1',
+        collectionKey: 'products',
+        requiredFields: ['id', 'name', 'productName', 'itemName', 'goodsName'],
+    },
+    {
+        id: 'cu.stores',
+        service: 'cu',
+        target: 'stores',
+        mode: 'quick',
+        path: '/api/cu/stores?keyword=%EA%B0%95%EB%82%A8&limit=1',
+        collectionKey: 'stores',
+        requiredFields: ['storeCode', 'storeName', 'name'],
+    },
+    {
+        id: 'emart24.products',
+        service: 'emart24',
+        target: 'products',
+        mode: 'quick',
+        path: '/api/emart24/products?keyword=%EC%BB%A4%ED%94%BC&pageSize=1',
+        collectionKey: 'products',
+        requiredFields: ['pluCd', 'goodsName', 'itemName', 'name'],
+        degradedFailurePatterns: EMART24_UPSTREAM_403_PATTERNS,
+    },
+    {
+        id: 'gs25.products',
+        service: 'gs25',
+        target: 'products',
+        mode: 'quick',
+        path: '/api/gs25/products?keyword=%EC%BD%9C%EB%9D%BC&limit=1',
+        collectionKey: 'products',
+        requiredFields: ['itemCode', 'itemName', 'name'],
+        degradedFailurePatterns: GS25_CLOUDFRONT_403_PATTERNS,
+    },
+    {
+        id: 'gs25.stores',
+        service: 'gs25',
+        target: 'stores',
+        mode: 'quick',
+        path: '/api/gs25/stores?keyword=%EA%B0%95%EB%82%A8&limit=1',
+        collectionKey: 'stores',
+        requiredFields: ['storeCode', 'storeName', 'name'],
+    },
+    {
+        id: 'seveneleven.products',
+        service: 'seveneleven',
+        target: 'products',
+        mode: 'quick',
+        path: '/api/seveneleven/products?query=%EC%BB%A4%ED%94%BC&size=1',
+        collectionKey: 'products',
+        requiredFields: ['itemCode', 'itemName', 'productNo', 'name'],
+        degradedFailurePatterns: SEVENELEVEN_UPSTREAM_403_PATTERNS,
+    },
+    {
+        id: 'lottemart.products',
+        service: 'lottemart',
+        target: 'products',
+        mode: 'quick',
+        path: '/api/lottemart/products?keyword=%EC%BD%9C%EB%9D%BC&storeCode=2301&area=%EC%84%9C%EC%9A%B8&pageLimit=1&source=zetta',
+        collectionKey: 'products',
+        requiredFields: ['productCode', 'name', 'productName'],
+    },
+    {
+        id: 'oliveyoung.products',
+        service: 'oliveyoung',
+        target: 'products',
+        mode: 'quick',
+        path: '/api/oliveyoung/products?keyword=%EB%A6%BD%EB%B0%A4&size=1',
+        collectionKey: 'products',
+        requiredFields: ['goodsNumber', 'goodsName', 'productNo', 'productName', 'name'],
+        timeoutMs: 5000,
+    },
+    {
+        id: 'megabox.theaters',
+        service: 'megabox',
+        target: 'theaters',
+        mode: 'quick',
+        path: '/api/megabox/theaters?keyword=%EA%B0%95%EB%82%A8&limit=1',
+        collectionKey: 'theaters',
+        requiredFields: ['theaterCode', 'theaterName', 'name'],
+    },
+    {
+        id: 'lottecinema.theaters',
+        service: 'lottecinema',
+        target: 'theaters',
+        mode: 'quick',
+        path: '/api/lottecinema/theaters?keyword=%EC%9E%A0%EC%8B%A4&limit=1',
+        collectionKey: 'theaters',
+        requiredFields: ['theaterCode', 'theaterName', 'name'],
+    },
+    {
+        id: 'cgv.theaters',
+        service: 'cgv',
+        target: 'theaters',
+        mode: 'quick',
+        path: '/api/cgv/theaters?keyword=%EA%B0%95%EB%82%A8&limit=1',
+        collectionKey: 'theaters',
+        requiredFields: ['theaterCode', 'theaterName', 'name'],
+    },
+    {
+        id: 'cu.inventory',
+        service: 'cu',
+        target: 'inventory',
+        mode: 'deep',
+        path: '/api/cu/inventory?keyword=%EC%BB%A4%ED%94%BC&size=1&storeLimit=0&storeCheck=false',
+        collectionKey: 'inventoryItems',
+        requiredFields: ['itemCode', 'itemName', 'name'],
+        degradedFailurePatterns: CU_UPSTREAM_BLOCK_PATTERNS,
+    },
+    {
+        id: 'emart24.inventory',
+        service: 'emart24',
+        target: 'inventory',
+        mode: 'deep',
+        path: '/api/emart24/inventory?keyword=%EC%BB%A4%ED%94%BC&storeKeyword=%EA%B0%95%EB%82%A8&limit=1',
+        collectionKey: 'inventoryItems',
+        requiredFields: ['pluCd', 'goodsName', 'itemName', 'name'],
+        degradedFailurePatterns: EMART24_UPSTREAM_403_PATTERNS,
+    },
+    {
+        id: 'gs25.inventory',
+        service: 'gs25',
+        target: 'inventory',
+        mode: 'deep',
+        path: '/api/gs25/inventory?keyword=%EC%BD%9C%EB%9D%BC&storeKeyword=%EA%B0%95%EB%82%A8&limit=1',
+        collectionKey: 'inventoryItems',
+        requiredFields: ['itemCode', 'itemName', 'name'],
+        degradedFailurePatterns: [
+            '401 Unauthorized',
+            '인증키가 제공되지 않음',
+            ...GS25_CLOUDFRONT_403_PATTERNS,
+        ],
+    },
+    {
+        id: 'seveneleven.inventory',
+        service: 'seveneleven',
+        target: 'inventory',
+        mode: 'deep',
+        path: '/api/seveneleven/inventory?keyword=%EC%BB%A4%ED%94%BC&storeKeyword=%EA%B0%95%EB%82%A8&size=1',
+        collectionKey: 'inventoryItems',
+        requiredFields: ['itemCode', 'itemName', 'productNo', 'name'],
+        degradedFailurePatterns: SEVENELEVEN_UPSTREAM_403_PATTERNS,
+    },
+    {
+        id: 'oliveyoung.inventory',
+        service: 'oliveyoung',
+        target: 'inventory',
+        mode: 'deep',
+        path: '/api/oliveyoung/inventory?keyword=%EC%84%A0%ED%81%AC%EB%A6%BC&storeKeyword=%EB%AA%85%EB%8F%99&size=1&storeLimit=1&stockCheckLimit=0',
+        collectionKey: 'inventoryProducts',
+        requiredFields: ['goodsNumber', 'goodsName', 'productNo', 'productName', 'name'],
+        timeoutMs: 5000,
+    },
+];

package/dist/api/healthCheckShape.js

@@ -0,0 +1,106 @@
+/**
+ * 헬스 체크 응답 shape 검사 유틸리티
+ */
+export function toCount(data) {
+    if (!data || typeof data !== 'object') {
+        return null;
+    }
+    const record = data;
+    if (typeof record.count === 'number') {
+        return record.count;
+    }
+    for (const key of ['products', 'stores', 'theaters', 'movies', 'showtimes']) {
+        const value = record[key];
+        if (Array.isArray(value)) {
+            return value.length;
+        }
+    }
+    if (record.inventory && typeof record.inventory === 'object') {
+        const inventory = record.inventory;
+        for (const key of ['products', 'items']) {
+            const value = inventory[key];
+            if (Array.isArray(value)) {
+                return value.length;
+            }
+        }
+    }
+    return null;
+}
+export function toFirstName(data) {
+    if (!data || typeof data !== 'object') {
+        return undefined;
+    }
+    const record = data;
+    for (const key of ['products', 'stores', 'theaters', 'movies', 'showtimes']) {
+        const value = record[key];
+        if (!Array.isArray(value) || !value[0] || typeof value[0] !== 'object') {
+            continue;
+        }
+        const item = value[0];
+        for (const nameKey of ['productName', 'itemName', 'goodsName', 'name', 'storeName', 'theaterName', 'movieName']) {
+            if (typeof item[nameKey] === 'string' && item[nameKey].trim().length > 0) {
+                return item[nameKey].trim();
+            }
+        }
+    }
+    if (record.inventory && typeof record.inventory === 'object') {
+        const inventory = record.inventory;
+        for (const key of ['products', 'items']) {
+            const value = inventory[key];
+            if (!Array.isArray(value) || !value[0] || typeof value[0] !== 'object') {
+                continue;
+            }
+            const item = value[0];
+            for (const nameKey of ['productName', 'itemName', 'goodsName', 'name']) {
+                if (typeof item[nameKey] === 'string' && item[nameKey].trim().length > 0) {
+                    return item[nameKey].trim();
+                }
+            }
+        }
+    }
+    return undefined;
+}
+function getCollectionItems(data, collectionKey) {
+    if (!data || typeof data !== 'object') {
+        return [];
+    }
+    const record = data;
+    if (collectionKey === 'inventoryProducts' || collectionKey === 'inventoryItems') {
+        const inventory = record.inventory;
+        if (!inventory || typeof inventory !== 'object') {
+            return [];
+        }
+        const key = collectionKey === 'inventoryProducts' ? 'products' : 'items';
+        const value = inventory[key];
+        return Array.isArray(value) ? value : [];
+    }
+    if (collectionKey && Array.isArray(record[collectionKey])) {
+        return record[collectionKey];
+    }
+    for (const key of ['products', 'stores', 'theaters', 'movies', 'showtimes']) {
+        /* c8 ignore next -- 현재 정의된 체크는 collectionKey를 명시한다. */
+        if (Array.isArray(record[key])) {
+            return record[key];
+        }
+    }
+    return [];
+}
+export function hasRequiredRepresentativeFields(data, collectionKey, requiredFields = []) {
+    /* c8 ignore next -- 현재 정의된 API 체크는 requiredFields를 명시한다. */
+    if (requiredFields.length === 0) {
+        return true;
+    }
+    const items = getCollectionItems(data, collectionKey);
+    if (items.length === 0) {
+        return true;
+    }
+    const first = items[0];
+    if (!first || typeof first !== 'object' || Array.isArray(first)) {
+        return false;
+    }
+    const record = first;
+    return requiredFields.some((field) => {
+        const value = record[field];
+        return typeof value === 'string' ? value.trim().length > 0 : value !== undefined && value !== null;
+    });
+}

package/dist/api/healthCheckTypes.js

@@ -0,0 +1,4 @@
+/**
+ * 헬스 체크 공통 타입
+ */
+export {};