daiso 1.0.5 → 1.0.7

package/README.md

@@ -5,9 +5,53 @@
 <br>
 <br>
 
-# Daiso MCP Server
+# Daiso MCP 및 Skill
 
-다이소(제품/매장/재고), 롯데마트(매장/상품), GS25(매장/상품/재고), 세븐일레븐(상품/매장/재고/인기검색어/카탈로그), CU(매장/재고), 이마트24(매장/상품/재고), 올리브영(매장/재고), 메가박스(지점/영화/시간표/좌석), 롯데시네마(지점/영화/좌석), CGV(극장/영화/시간표) 조회 기능을 AI에 연결합니다.
+다이소(제품/매장/재고), 주변 음식점/카페, 롯데마트(매장/상품), GS25(매장/상품/재고), 세븐일레븐(상품/매장/재고/인기검색어/카탈로그), CU(매장/재고), 이마트24(매장/상품/재고), 올리브영(매장/재고), 메가박스(지점/영화/시간표/좌석), 롯데시네마(지점/영화/좌석), CGV(극장/영화/시간표) 조회 기능을 MCP, CLI, Codex Skill로 AI에 연결합니다.
+
+<br>
+
+**MCP:** `https://mcp.aka.page` · **CLI:** `npx daiso` · **Skill:** `clawhub install daiso-cli`
+
+**ClawHub:** [clawhub.ai/hmmhmmhm/daiso-cli](https://clawhub.ai/hmmhmmhm/daiso-cli)
+
+한국 로컬 리테일과 영화관 조회를 MCP, CLI, Codex Skill로 연결하는 도구입니다.
+
+<br>
+
+<h3>지원 서비스</h3>
+
+<table>
+  <thead>
+    <tr>
+      <th>분류</th>
+      <th>서비스</th>
+      <th>조회 기능</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>장소</td>
+      <td>네이버 지역 검색</td>
+      <td>음식점, 카페, 디저트, 주변 장소</td>
+    </tr>
+    <tr>
+      <td>리테일</td>
+      <td>다이소, 올리브영, 롯데마트</td>
+      <td>상품, 매장, 재고</td>
+    </tr>
+    <tr>
+      <td>편의점</td>
+      <td>GS25, 세븐일레븐, CU, 이마트24</td>
+      <td>상품, 매장, 재고, 인기검색어, 카탈로그</td>
+    </tr>
+    <tr>
+      <td>영화관</td>
+      <td>CGV, 메가박스, 롯데시네마</td>
+      <td>극장, 영화, 시간표, 잔여 좌석</td>
+    </tr>
+  </tbody>
+</table>
 
 <br>
 
@@ -21,11 +65,11 @@
 **[실시간 서비스 상태 보기](https://aka-page.betteruptime.com/)**
 
 <!-- WORKERS_INVOCATIONS_CHART:START -->
-<h3>Cloudflare Workers 호출량 (2026-03-01 ~ 2026-05-16, 77일)</h3>
+<h3>Cloudflare Workers 호출량 (2026-03-01 ~ 2026-05-21, 82일)</h3>
 
-<img src="./assets/analytics/workers-invocations.png?v=2026-05-16T15:44:19.119Z" alt="Cloudflare Workers 호출량 그래프 (2026-03-01 ~ 2026-05-16)" width="100%">
+<img src="./assets/analytics/workers-invocations.png?v=2026-05-23T04:50:41.937Z" alt="Cloudflare Workers 호출량 그래프 (2026-03-01 ~ 2026-05-21)" width="100%">
 
-<sub>기준 워커: <code>daiso-mcp</code> · 마지막 갱신: 2026-05-17 00:44 KST</sub>
+<sub>기준 워커: <code>daiso-mcp</code> · 마지막 갱신: 2026-05-23 13:50 KST</sub>
 
 <!-- WORKERS_INVOCATIONS_CHART:END -->
 
@@ -70,6 +114,8 @@ GS25 mcp로 강남 근처 매장과 오감자 재고 알려줘
 세븐일레븐 mcp로 안산 중앙역 근처 매장 찾아줘
 세븐일레븐 mcp로 안산 중앙역 근처 세븐일레븐에서 핫식스 재고 알려줘
 세븐일레븐 mcp로 인기 검색어와 카탈로그 요약 알려줘
+강남역 근처 카페 찾아줘
+성수동 근처 브런치 음식점 찾아줘
 메가박스 mcp로 강남점 영화와 잔여 좌석 알려줘
 롯데시네마 mcp로 월드타워 근처 지점과 상영 영화 알려줘
 롯데시네마 mcp로 월드타워 잔여 좌석 알려줘
@@ -163,6 +209,19 @@ AI: (https://mcp.aka.page/api/cgv/timetable?playDate=20260315&keyword=안산%20
 
 <br>
 
+### 바로 실행해보기
+
+AI 앱 연동 없이 터미널에서 바로 확인할 수 있습니다.
+
+```bash
+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
+```
+
+<br>
+
 ### MCP 서버 URL / CLI (고급)
 
 AI 앱 대신 직접 연결하거나 스크립트에서 사용할 때만 참고하세요.
@@ -195,6 +254,8 @@ npx daiso product 1034604
 npx daiso stores 강남역
 npx daiso inventory 1034604 --keyword 강남역
 npx daiso display-location 1034604 04515
+npx daiso places 강남역 --category cafe --limit 5
+npx daiso places 성수동 --keyword 브런치 --limit 5
 npx daiso cu-stores 강남
 npx daiso cu-inventory 과자 --storeKeyword 강남
 npx daiso lottemart-stores 잠실 --area 서울 --limit 10
@@ -216,6 +277,17 @@ npx daiso get /api/cgv/movies --playDate 20260307 --theaterCode 0056
 npx daiso products 수납박스 --json
 ```
 
+### Codex Skill
+
+이 저장소는 MCP 서버뿐 아니라 에이전트가 `npx daiso` CLI를 직접 고를 수 있게 하는 Codex Skill도 제공합니다.
+
+- ClawHub: `clawhub install daiso-cli`
+- 공개 페이지: `https://clawhub.ai/hmmhmmhm/daiso-cli`
+- 스킬 파일: `skills/daiso-cli/SKILL.md`
+- 명령 맵: `skills/daiso-cli/references/cli-command-map.md`
+- 기본 원칙: 쉘 실행이 가능한 환경에서는 CLI를 우선 사용하고, AI 앱 연결이 필요할 때는 MCP 서버 URL `https://mcp.aka.page`를 사용합니다.
+- 구조화 결과가 필요하면 스킬은 `npx daiso ... --json` 형태를 선택합니다.
+
 ### OpenAPI 스펙
 
 - OpenAI 챗봇 등록용 축약 스펙: `https://mcp.aka.page/openapi.json`
@@ -223,24 +295,45 @@ npx daiso products 수납박스 --json
 - 전체 개별 엔드포인트 스펙(JSON): `https://mcp.aka.page/openapi-full.json`
 - 전체 개별 엔드포인트 스펙(YAML): `https://mcp.aka.page/openapi-full.yaml`
 
+### MCP 표준 응답 모델
+
+MCP 도구 응답은 각 서비스의 원본 필드를 유지하면서, 클라이언트가 공통 UI를 만들 수 있도록 `standard` 필드를 함께 제공합니다.
+
+- `standard.products`: 상품/영화 목록을 `code`, `name`, `price`, `imageUrl`, `raw` 형태로 정규화합니다.
+- `standard.stores`: 매장 목록을 `code`, `name`, `address`, `distanceMeters`, `raw` 형태로 정규화합니다.
+- `standard.theaters`: 영화관 목록을 `code`, `name`, `address`, `distanceMeters`, `raw` 형태로 정규화합니다.
+- `standard.places`: 음식점/카페 같은 장소 목록을 `name`, `address`, `raw` 중심으로 정규화합니다.
+
 ### 운영 헬스 체크
 
 공개 상태 페이지: **[Daiso MCP Status](https://aka-page.betteruptime.com/)**
 
+주변 음식점/카페 검색은 네이버 지역 검색 API를 사용합니다. 로컬 실행이나 배포 환경에는 `NAVER_CLIENT_ID`, `NAVER_CLIENT_SECRET`을 설정하세요.
+
 서비스별 API 상태를 즉시 확인할 때는 `GET /api/health/checks`를 사용합니다. 이 엔드포인트는 `HEALTH_CHECK_SECRET` 환경 변수가 설정되어 있어야 하며, 요청에는 `Authorization: Bearer <secret>` 또는 `x-health-check-key: <secret>` 헤더가 필요합니다. 내부 체크 요청의 기준 URL은 `HEALTH_CHECK_BASE_URL`로 지정할 수 있습니다.
 
 ```bash
 curl -H "Authorization: Bearer $HEALTH_CHECK_SECRET" \
-  "https://mcp.aka.page/api/health/checks?check=lottemart.products&fresh=true&includeSamples=true"
+  "https://mcp.aka.page/api/health/checks?mode=full&fresh=true&includeSamples=true&timeoutMs=20000&slowThresholdMs=9000"
 ```
 
 주요 쿼리:
 
 - `service=gs25`: 특정 서비스만 확인
 - `check=lottemart.products`: 특정 체크만 확인
-- `mode=quick|deep`: 체크 모드 선택
+- `mode=quick|deep|full`: 체크 모드 선택
 - `fresh=true`: 60초 캐시 우회
 - `includeSamples=true`: 첫 결과 이름 샘플 포함
+- `timeoutMs=20000`: 체크별 요청 제한 시간
+- `slowThresholdMs=9000`: 지정 시간보다 느린 성공 응답을 degraded로 표시
+
+상태 기준:
+
+- `ok`: 필수 응답 구조와 최소 결과가 정상입니다.
+- `degraded`: 기능은 살아 있지만 빈 결과, 느린 응답, 응답 구조 변화 등 확인이 필요합니다.
+- `fail`: 외부 API 오류, 타임아웃, 인증 문제처럼 실제 장애로 봐야 합니다.
+
+Better Stack 같은 외부 모니터링에서는 `fail`을 장애 알림 기준으로 보고, `degraded`는 느린 외부 API나 응답 품질 저하를 추적하는 경고 신호로 봅니다.
 
 배포 전 로컬에서 CLI 모드까지 확인할 때는 아래 명령을 사용합니다.
 
@@ -315,6 +408,7 @@ daiso 인터랙티브 모드
 
 - [@thecats1105](https://github.com/thecats1105): 다이소 진열 위치 조회 도구(`daiso_get_display_location`) 구현 및 API/테스트 연동
 - [@betterthanhajin](https://github.com/betterthanhajin): CGV 서비스 프로바이더 구현(극장/영화/시간표 도구, 라우트·스펙·테스트 추가)
+- [@LLagoon3](https://github.com/LLagoon3): 다이소 매장 재고 조회 신규 인증 흐름 전환 및 관련 테스트 보강
 - [제로초님](https://youtube.com/shorts/ZgIqA1NCEp0?si=UW0pKsSpqmEi7lXG): 프로젝트 홍보 도움
 
 <br>

package/dist/api/actionsProxy.js

@@ -3,34 +3,124 @@
  */
 export const ACTION_QUERY_DEFINITIONS = [
     { action: 'daisoSearchProducts', summary: '다이소 제품 검색', targetPath: '/api/daiso/products' },
-    { action: 'daisoGetProduct', summary: '다이소 제품 상세 조회', targetPath: '/api/daiso/products/:productId', pathParam: 'productId' },
+    {
+        action: 'daisoGetProduct',
+        summary: '다이소 제품 상세 조회',
+        targetPath: '/api/daiso/products/:productId',
+        pathParam: 'productId',
+    },
     { action: 'daisoFindStores', summary: '다이소 매장 검색', targetPath: '/api/daiso/stores' },
-    { action: 'daisoCheckInventory', summary: '다이소 재고 조회', targetPath: '/api/daiso/inventory' },
-    { action: 'daisoGetDisplayLocation', summary: '다이소 진열 위치 조회', targetPath: '/api/daiso/display-location' },
-    { action: 'oliveyoungSearchProducts', summary: '올리브영 상품 검색', targetPath: '/api/oliveyoung/products' },
-    { action: 'oliveyoungFindStores', summary: '올리브영 매장 검색', targetPath: '/api/oliveyoung/stores' },
-    { action: 'oliveyoungCheckInventory', summary: '올리브영 재고 조회', targetPath: '/api/oliveyoung/inventory' },
+    {
+        action: 'daisoCheckInventory',
+        summary: '다이소 재고 조회',
+        targetPath: '/api/daiso/inventory',
+    },
+    {
+        action: 'daisoGetDisplayLocation',
+        summary: '다이소 진열 위치 조회',
+        targetPath: '/api/daiso/display-location',
+    },
+    {
+        action: 'oliveyoungSearchProducts',
+        summary: '올리브영 상품 검색',
+        targetPath: '/api/oliveyoung/products',
+    },
+    {
+        action: 'oliveyoungFindStores',
+        summary: '올리브영 매장 검색',
+        targetPath: '/api/oliveyoung/stores',
+    },
+    {
+        action: 'oliveyoungCheckInventory',
+        summary: '올리브영 재고 조회',
+        targetPath: '/api/oliveyoung/inventory',
+    },
     { action: 'cuFindStores', summary: 'CU 매장 검색', targetPath: '/api/cu/stores' },
     { action: 'cuCheckInventory', summary: 'CU 재고 조회', targetPath: '/api/cu/inventory' },
     { action: 'emart24FindStores', summary: '이마트24 매장 검색', targetPath: '/api/emart24/stores' },
-    { action: 'emart24SearchProducts', summary: '이마트24 상품 검색', targetPath: '/api/emart24/products' },
-    { action: 'emart24CheckInventory', summary: '이마트24 재고 조회', targetPath: '/api/emart24/inventory' },
-    { action: 'lottemartFindStores', summary: '롯데마트 매장 검색', targetPath: '/api/lottemart/stores' },
-    { action: 'lottemartSearchProducts', summary: '롯데마트 상품 검색', targetPath: '/api/lottemart/products' },
+    {
+        action: 'emart24SearchProducts',
+        summary: '이마트24 상품 검색',
+        targetPath: '/api/emart24/products',
+    },
+    {
+        action: 'emart24CheckInventory',
+        summary: '이마트24 재고 조회',
+        targetPath: '/api/emart24/inventory',
+    },
+    {
+        action: 'lottemartFindStores',
+        summary: '롯데마트 매장 검색',
+        targetPath: '/api/lottemart/stores',
+    },
+    {
+        action: 'lottemartSearchProducts',
+        summary: '롯데마트 상품 검색',
+        targetPath: '/api/lottemart/products',
+    },
     { action: 'gs25FindStores', summary: 'GS25 매장 검색', targetPath: '/api/gs25/stores' },
     { action: 'gs25SearchProducts', summary: 'GS25 상품 검색', targetPath: '/api/gs25/products' },
     { action: 'gs25CheckInventory', summary: 'GS25 재고 조회', targetPath: '/api/gs25/inventory' },
-    { action: 'sevenelevenSearchProducts', summary: '세븐일레븐 상품 검색', targetPath: '/api/seveneleven/products' },
-    { action: 'sevenelevenSearchStores', summary: '세븐일레븐 매장 검색', targetPath: '/api/seveneleven/stores' },
-    { action: 'sevenelevenCheckInventory', summary: '세븐일레븐 재고 조회', targetPath: '/api/seveneleven/inventory' },
-    { action: 'sevenelevenGetPopwords', summary: '세븐일레븐 인기 검색어 조회', targetPath: '/api/seveneleven/popwords' },
-    { action: 'sevenelevenGetCatalog', summary: '세븐일레븐 카탈로그 조회', targetPath: '/api/seveneleven/catalog' },
-    { action: 'megaboxFindTheaters', summary: '메가박스 지점 검색', targetPath: '/api/megabox/theaters' },
-    { action: 'megaboxListMovies', summary: '메가박스 영화 목록 조회', targetPath: '/api/megabox/movies' },
-    { action: 'megaboxGetSeats', summary: '메가박스 잔여 좌석 조회', targetPath: '/api/megabox/seats' },
-    { action: 'lottecinemaFindTheaters', summary: '롯데시네마 지점 검색', targetPath: '/api/lottecinema/theaters' },
-    { action: 'lottecinemaListMovies', summary: '롯데시네마 영화 목록 조회', targetPath: '/api/lottecinema/movies' },
-    { action: 'lottecinemaGetSeats', summary: '롯데시네마 잔여 좌석 조회', targetPath: '/api/lottecinema/seats' },
+    {
+        action: 'sevenelevenSearchProducts',
+        summary: '세븐일레븐 상품 검색',
+        targetPath: '/api/seveneleven/products',
+    },
+    {
+        action: 'sevenelevenSearchStores',
+        summary: '세븐일레븐 매장 검색',
+        targetPath: '/api/seveneleven/stores',
+    },
+    {
+        action: 'sevenelevenCheckInventory',
+        summary: '세븐일레븐 재고 조회',
+        targetPath: '/api/seveneleven/inventory',
+    },
+    {
+        action: 'sevenelevenGetPopwords',
+        summary: '세븐일레븐 인기 검색어 조회',
+        targetPath: '/api/seveneleven/popwords',
+    },
+    {
+        action: 'sevenelevenGetCatalog',
+        summary: '세븐일레븐 카탈로그 조회',
+        targetPath: '/api/seveneleven/catalog',
+    },
+    {
+        action: 'placesSearchNearby',
+        summary: '음식점/카페 등 주변 장소 검색',
+        targetPath: '/api/places/search',
+    },
+    {
+        action: 'megaboxFindTheaters',
+        summary: '메가박스 지점 검색',
+        targetPath: '/api/megabox/theaters',
+    },
+    {
+        action: 'megaboxListMovies',
+        summary: '메가박스 영화 목록 조회',
+        targetPath: '/api/megabox/movies',
+    },
+    {
+        action: 'megaboxGetSeats',
+        summary: '메가박스 잔여 좌석 조회',
+        targetPath: '/api/megabox/seats',
+    },
+    {
+        action: 'lottecinemaFindTheaters',
+        summary: '롯데시네마 지점 검색',
+        targetPath: '/api/lottecinema/theaters',
+    },
+    {
+        action: 'lottecinemaListMovies',
+        summary: '롯데시네마 영화 목록 조회',
+        targetPath: '/api/lottecinema/movies',
+    },
+    {
+        action: 'lottecinemaGetSeats',
+        summary: '롯데시네마 잔여 좌석 조회',
+        targetPath: '/api/lottecinema/seats',
+    },
     { action: 'cgvFindTheaters', summary: 'CGV 극장 검색', targetPath: '/api/cgv/theaters' },
     { action: 'cgvSearchMovies', summary: 'CGV 영화 목록 조회', targetPath: '/api/cgv/movies' },
     { action: 'cgvGetTimetable', summary: 'CGV 시간표 조회', targetPath: '/api/cgv/timetable' },

package/dist/api/configStatus.js

@@ -0,0 +1,23 @@
+function isConfigured(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+export function buildConfigStatus(bindings) {
+    return {
+        googleMapsApiKey: {
+            configured: isConfigured(bindings?.GOOGLE_MAPS_API_KEY),
+            usedBy: ['gs25', 'cu', 'lottemart', 'megabox', 'lottecinema', 'cgv'],
+        },
+        zyteApiKey: {
+            configured: isConfigured(bindings?.ZYTE_API_KEY),
+            usedBy: ['oliveyoung', 'gs25', 'lottemart', 'cgv'],
+        },
+        naverLocalSearch: {
+            configured: isConfigured(bindings?.NAVER_CLIENT_ID) && isConfigured(bindings?.NAVER_CLIENT_SECRET),
+            usedBy: ['places'],
+        },
+        healthCheckSecret: {
+            configured: isConfigured(bindings?.HEALTH_CHECK_SECRET),
+            usedBy: ['health-checks'],
+        },
+    };
+}

package/dist/api/gs25Handlers.js

@@ -3,7 +3,7 @@
  */
 /* c8 ignore start */
 import { errorResponse, successResponse } from './response.js';
-import { attachDistanceToGs25Stores, fetchGs25SearchProducts, fetchGs25Stores, filterGs25StoresByKeyword, geocodeGs25Address, selectGs25StoresForKeyword, sortGs25Stores, } from '../services/gs25/client.js';
+import { attachDistanceToGs25Stores, fetchGs25SearchProducts, fetchGs25Stores, fetchGs25WebStores, filterGs25StoresByKeyword, geocodeGs25Address, selectGs25StoresForKeyword, sortGs25Stores, } from '../services/gs25/client.js';
 const GS25_FALLBACK_STORE_LOOKUP_ITEM_CODE = '8801117752804';
 /**
  * GS25 매장 검색 API 핸들러
@@ -21,7 +21,8 @@ export async function handleGs25FindStores(c) {
     let longitude = typeof parsedLng === 'number' && Number.isFinite(parsedLng) ? parsedLng : undefined;
     let geocodeUsed = false;
     try {
-        if ((typeof latitude !== 'number' || typeof longitude !== 'number') && keyword.trim().length > 0) {
+        if ((typeof latitude !== 'number' || typeof longitude !== 'number') &&
+            keyword.trim().length > 0) {
             const geocoded = await geocodeGs25Address(keyword, {
                 timeout: 15000,
                 googleMapsApiKey: c.env?.GOOGLE_MAPS_API_KEY,
@@ -38,9 +39,12 @@ export async function handleGs25FindStores(c) {
             longitude,
         }, {
             timeout: 20000,
+            zyteApiKey: c.env?.ZYTE_API_KEY,
         });
         let fallbackUsed = false;
-        if (storeResult.stores.length === 0 && typeof latitude === 'number' && typeof longitude === 'number') {
+        if (storeResult.stores.length === 0 &&
+            typeof latitude === 'number' &&
+            typeof longitude === 'number') {
             try {
                 const fallbackResult = await fetchGs25Stores({
                     serviceCode,
@@ -51,6 +55,7 @@ export async function handleGs25FindStores(c) {
                     useCache: false,
                 }, {
                     timeout: 20000,
+                    zyteApiKey: c.env?.ZYTE_API_KEY,
                 });
                 if (fallbackResult.stores.length > 0) {
                     storeResult = fallbackResult;
@@ -61,6 +66,24 @@ export async function handleGs25FindStores(c) {
                 fallbackUsed = false;
             }
         }
+        if (storeResult.stores.length === 0 && keyword.trim().length > 0) {
+            try {
+                const webStoreResult = await fetchGs25WebStores(keyword, {
+                    timeout: 20000,
+                });
+                if (webStoreResult.stores.length > 0) {
+                    storeResult = {
+                        totalCount: webStoreResult.totalCount,
+                        stores: webStoreResult.stores,
+                        cacheHit: false,
+                    };
+                    fallbackUsed = true;
+                }
+            }
+            catch {
+                fallbackUsed = false;
+            }
+        }
         const selected = selectGs25StoresForKeyword(storeResult.stores, keyword, {
             relaxWhenEmpty: typeof latitude === 'number' && typeof longitude === 'number',
         });
@@ -98,7 +121,10 @@ export async function handleGs25SearchProducts(c) {
         return errorResponse(c, 'MISSING_QUERY', '검색어(keyword)를 입력해주세요.');
     }
     try {
-        const products = await fetchGs25SearchProducts(keyword, { timeout: 20000 });
+        const products = await fetchGs25SearchProducts(keyword, {
+            timeout: 20000,
+            zyteApiKey: c.env?.ZYTE_API_KEY,
+        });
         const limitedProducts = products.slice(0, limit);
         return successResponse(c, {
             keyword,
@@ -142,23 +168,35 @@ export async function handleGs25CheckInventory(c) {
         return errorResponse(c, 'MISSING_QUERY', '검색어(keyword) 또는 상품 코드(itemCode)를 입력해주세요.');
     }
     try {
-        if ((typeof latitude !== 'number' || typeof longitude !== 'number') && storeKeyword.trim().length > 0) {
-            const baseStores = await fetchGs25Stores({
-                serviceCode,
-            }, {
-                timeout: 20000,
+        if ((typeof latitude !== 'number' || typeof longitude !== 'number') &&
+            storeKeyword.trim().length > 0) {
+            const directGeocoded = await geocodeGs25Address(storeKeyword, {
+                timeout: 15000,
+                googleMapsApiKey: c.env?.GOOGLE_MAPS_API_KEY,
             });
-            const firstAddress = filterGs25StoresByKeyword(baseStores.stores, storeKeyword).find((store) => store.address.trim().length > 0)
-                ?.address || '';
-            if (firstAddress.length > 0) {
-                const geocoded = await geocodeGs25Address(firstAddress, {
-                    timeout: 15000,
-                    googleMapsApiKey: c.env?.GOOGLE_MAPS_API_KEY,
+            if (directGeocoded) {
+                latitude = directGeocoded.latitude;
+                longitude = directGeocoded.longitude;
+                geocodeUsed = true;
+            }
+            else {
+                const baseStores = await fetchGs25Stores({
+                    serviceCode,
+                }, {
+                    timeout: 20000,
+                    zyteApiKey: c.env?.ZYTE_API_KEY,
                 });
-                if (geocoded) {
-                    latitude = geocoded.latitude;
-                    longitude = geocoded.longitude;
-                    geocodeUsed = true;
+                const firstAddress = filterGs25StoresByKeyword(baseStores.stores, storeKeyword).find((store) => store.address.trim().length > 0)?.address || '';
+                if (firstAddress.length > 0) {
+                    const geocoded = await geocodeGs25Address(firstAddress, {
+                        timeout: 15000,
+                        googleMapsApiKey: c.env?.GOOGLE_MAPS_API_KEY,
+                    });
+                    if (geocoded) {
+                        latitude = geocoded.latitude;
+                        longitude = geocoded.longitude;
+                        geocodeUsed = true;
+                    }
                 }
             }
         }
@@ -177,10 +215,14 @@ export async function handleGs25CheckInventory(c) {
                 useCache: false,
             }, {
                 timeout: 20000,
+                zyteApiKey: c.env?.ZYTE_API_KEY,
             });
         }
         else {
-            const searchProducts = await fetchGs25SearchProducts(keyword, { timeout: 20000 });
+            const searchProducts = await fetchGs25SearchProducts(keyword, {
+                timeout: 20000,
+                zyteApiKey: c.env?.ZYTE_API_KEY,
+            });
             firstProduct = searchProducts.find((p) => p.itemCode.length > 0);
             if (firstProduct) {
                 resolvedItemCode = firstProduct.itemCode;
@@ -194,6 +236,7 @@ export async function handleGs25CheckInventory(c) {
                     useCache: false,
                 }, {
                     timeout: 20000,
+                    zyteApiKey: c.env?.ZYTE_API_KEY,
                 });
             }
             else {
@@ -206,6 +249,7 @@ export async function handleGs25CheckInventory(c) {
                     useCache: false,
                 }, {
                     timeout: 20000,
+                    zyteApiKey: c.env?.ZYTE_API_KEY,
                 });
             }
         }
@@ -216,8 +260,10 @@ export async function handleGs25CheckInventory(c) {
         const withDistance = attachDistanceToGs25Stores(filtered, latitude, longitude);
         const stores = sortGs25Stores(withDistance).slice(0, storeLimit);
         // 상품 정보: searchProducts에서 먼저 가져오고, 없으면 stores에서
-        const productName = firstProduct?.itemName || firstProduct?.shortItemName ||
-            filtered.find((item) => item.searchItemName.length > 0)?.searchItemName || null;
+        const productName = firstProduct?.itemName ||
+            firstProduct?.shortItemName ||
+            filtered.find((item) => item.searchItemName.length > 0)?.searchItemName ||
+            null;
         const productPrice = filtered.find((item) => item.searchItemSellPrice !== null)?.searchItemSellPrice ?? null;
         const inStockStoreCount = filtered.filter((item) => item.realStockQuantity > 0).length;
         const totalStockQuantity = filtered.reduce((sum, item) => sum + Math.max(item.realStockQuantity, 0), 0);

package/dist/api/handlers.js

@@ -8,6 +8,19 @@ import { enrichOliveyoungProductsWithNearbyStoreInventory, fetchOliveyoungProduc
 import { fetchCuStock, fetchCuStores, geocodeCuAddress } from '../services/cu/client.js';
 import { errorResponse, successResponse } from './response.js';
 export { handleCheckInventory, handleFindStores, handleGetDisplayLocation, handleGetProduct, handleSearchProducts, } from './daisoHandlers.js';
+function parseBooleanQuery(value, defaultValue = false) {
+    if (!value) {
+        return defaultValue;
+    }
+    const normalized = value.trim().toLowerCase();
+    if (normalized === 'true' || normalized === '1' || normalized === 'y') {
+        return true;
+    }
+    if (normalized === 'false' || normalized === '0' || normalized === 'n') {
+        return false;
+    }
+    return defaultValue;
+}
 /**
  * 올리브영 상품 검색 API 핸들러
  * GET /api/oliveyoung/products?keyword={검색어}
@@ -18,6 +31,8 @@ export async function handleOliveyoungSearchProducts(c) {
     const size = parseInt(c.req.query('size') || '20');
     const sort = c.req.query('sort') || '01';
     const includeSoldOut = c.req.query('includeSoldOut') === 'true';
+    const parsedTimeoutMs = parseInt(c.req.query('timeoutMs') || '15000', 10);
+    const timeoutMs = Number.isFinite(parsedTimeoutMs) && parsedTimeoutMs > 0 ? parsedTimeoutMs : 15000;
     if (keyword.trim().length === 0) {
         return errorResponse(c, 'MISSING_QUERY', '검색어(keyword)를 입력해주세요.');
     }
@@ -30,6 +45,7 @@ export async function handleOliveyoungSearchProducts(c) {
             includeSoldOut,
         }, {
             apiKey: c.env?.ZYTE_API_KEY,
+            timeout: timeoutMs,
         });
         return successResponse(c, {
             keyword,
@@ -54,6 +70,8 @@ export async function handleOliveyoungFindStores(c) {
     const lng = parseFloat(c.req.query('lng') || '126.978');
     const pageIdx = parseInt(c.req.query('pageIdx') || '1');
     const limit = parseInt(c.req.query('limit') || '20');
+    const parsedTimeoutMs = parseInt(c.req.query('timeoutMs') || '15000', 10);
+    const timeoutMs = Number.isFinite(parsedTimeoutMs) && parsedTimeoutMs > 0 ? parsedTimeoutMs : 15000;
     try {
         const result = await fetchOliveyoungStores({
             latitude: lat,
@@ -62,6 +80,7 @@ export async function handleOliveyoungFindStores(c) {
             searchWords: keyword,
         }, {
             apiKey: c.env?.ZYTE_API_KEY,
+            timeout: timeoutMs,
         });
         return successResponse(c, {
             stores: result.stores.slice(0, limit),
@@ -86,6 +105,10 @@ export async function handleOliveyoungCheckInventory(c) {
     const sort = c.req.query('sort') || '01';
     const includeSoldOut = c.req.query('includeSoldOut') === 'true';
     const storeLimit = parseInt(c.req.query('storeLimit') || '10');
+    const parsedTimeoutMs = parseInt(c.req.query('timeoutMs') || '15000', 10);
+    const timeoutMs = Number.isFinite(parsedTimeoutMs) && parsedTimeoutMs > 0 ? parsedTimeoutMs : 15000;
+    const parsedStockCheckLimit = parseInt(c.req.query('stockCheckLimit') || '5', 10);
+    const stockCheckLimit = Number.isFinite(parsedStockCheckLimit) && parsedStockCheckLimit >= 0 ? parsedStockCheckLimit : 5;
     if (!keyword || keyword.trim().length === 0) {
         return errorResponse(c, 'MISSING_QUERY', '검색어(keyword)를 입력해주세요.');
     }
@@ -98,6 +121,7 @@ export async function handleOliveyoungCheckInventory(c) {
                 searchWords: storeKeyword,
             }, {
                 apiKey: c.env.ZYTE_API_KEY,
+                timeout: timeoutMs,
             }),
             fetchOliveyoungProducts({
                 keyword,
@@ -107,15 +131,17 @@ export async function handleOliveyoungCheckInventory(c) {
                 includeSoldOut,
             }, {
                 apiKey: c.env.ZYTE_API_KEY,
+                timeout: timeoutMs,
             }),
         ]);
         const enrichedInventory = await enrichOliveyoungProductsWithNearbyStoreInventory(productResult.products, {
             latitude: lat,
             longitude: lng,
             storeKeyword,
-            maxProducts: Math.min(productResult.products.length, 5),
+            maxProducts: Math.min(productResult.products.length, stockCheckLimit),
         }, {
             apiKey: c.env.ZYTE_API_KEY,
+            timeout: timeoutMs,
         });
         const inStockCount = enrichedInventory.products.filter((product) => product.inStock).length;
         return successResponse(c, {
@@ -191,6 +217,7 @@ export async function handleCuCheckInventory(c) {
     const offset = parseInt(c.req.query('offset') || '0');
     const searchSort = c.req.query('searchSort') || 'recom';
     const storeLimit = parseInt(c.req.query('storeLimit') || '10');
+    const storeCheck = parseBooleanQuery(c.req.query('storeCheck'), true);
     if (!keyword || keyword.trim().length === 0) {
         return errorResponse(c, 'MISSING_QUERY', '검색어(keyword)를 입력해주세요.');
     }
@@ -207,9 +234,11 @@ export async function handleCuCheckInventory(c) {
         const hasInputLocation = typeof lat === 'number' && typeof lng === 'number';
         const resolvedLat = hasInputLocation ? lat : undefined;
         const resolvedLng = hasInputLocation ? lng : undefined;
-        let storeResult = null;
+        let storeResult = storeCheck
+            ? null
+            : { totalCount: 0, stores: [] };
         // 좌표 미입력 + 매장 키워드 입력 시, 키워드 기반 매장 검색 결과를 우선 사용합니다.
-        if (!hasInputLocation && storeKeyword.trim().length > 0) {
+        if (storeCheck && !hasInputLocation && storeKeyword.trim().length > 0) {
             const keywordStoreResult = await fetchCuStores({
                 searchWord: storeKeyword,
             }, {