daiso 1.0.9 → 1.1.0

package/README.md

@@ -1,3 +1,5 @@
+[![MCP Toplist](https://mcptoplist.com/badge/glama%2Fhmmhmmhm%2Fdaiso-mcp.svg)](https://mcptoplist.com/server/glama%2Fhmmhmmhm%2Fdaiso-mcp)
+
 <div align="center">
 
 <img src="./assets/logo.svg" alt="Daiso MCP" width="120" height="120">
@@ -7,7 +9,9 @@
 
 # Daiso MCP 및 Skill
 
-다이소(제품/매장/재고), 키 없는 통합 가격 후보 비교, 주변 음식점/카페, 개발자 요청 제출, 롯데마트(매장/상품), GS25(매장/상품/재고), 세븐일레븐(상품/매장/재고/인기검색어/카탈로그), CU(매장/재고), 이마트24(매장/상품/재고), 올리브영(매장/재고), 메가박스(지점/영화/시간표/좌석), 롯데시네마(지점/영화/좌석), CGV(극장/영화/시간표) 조회 기능을 MCP, CLI, Codex Skill로 AI에 연결합니다.
+다이소(제품/매장/재고), 상품 가격 비교, 주변 음식점/카페, 주유소/유가, 개발자 요청 제출, 롯데마트(매장/상품), GS25(매장/상품/재고), 세븐일레븐(상품/매장/재고/인기검색어/카탈로그), CU(매장/재고), 이마트24(매장/상품/재고), 올리브영(매장/재고), 메가박스(지점/영화/시간표/좌석), 롯데시네마(지점/영화/좌석), CGV(극장/영화/시간표), 디트릭스(독립·예술영화관/상영작/잔여 좌석) 조회 기능을 MCP, CLI, Codex Skill로 AI에 연결합니다.
+
+디트릭스의 지원 범위와 CLI 예시는 [독립·예술영화관 조회 가이드](docs/dtryx.md)를 참고하세요.
 
 <br>
 
@@ -15,7 +19,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 +40,15 @@
       <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>
@@ -75,11 +85,19 @@
 **[실시간 서비스 상태 보기](https://aka-page.betteruptime.com/)**
 
 <!-- WORKERS_INVOCATIONS_CHART:START -->
-<h3>Cloudflare Workers 호출량 (2026-03-01 ~ 2026-05-27, 88일)</h3>
+<h3>Cloudflare 요청 수 (2026-08-16 ~ 2026-09-14, 30일)</h3>
 
-<img src="./assets/analytics/workers-invocations.png?v=2026-05-27T22:46:35.568Z" alt="Cloudflare Workers 호출량 그래프 (2026-03-01 ~ 2026-05-27)" width="100%">
+<img src="./assets/analytics/workers-invocations.png?v=2026-09-14T19:51:30.925Z" alt="Cloudflare 요청 수 그래프 (2026-08-16 ~ 2026-09-14)" width="100%">
+
+<sub>기준 워커: <code>daiso-mcp</code> · 마지막 갱신: 2026-09-15 04:51 KST</sub>
+<br><sub>집계: Worker 실행 + 루트 GET 리디렉션 요청 · 사용자 수와 다릅니다.</sub>
+
+</div>
 
-<sub>기준 워커: <code>daiso-mcp</code> · 마지막 갱신: 2026-05-28 07:46 KST</sub>
+> [!IMPORTANT]
+> 최근 공개 서버 사용량이 크게 증가하여 2026년 7월 18일부터 올리브영·CGV·CU·GS25·롯데마트의 검색을 포함한 공개 GET API에 IP당 하루 합산 3,000회(KST 기준)의 호출 제한을 적용합니다. 한도를 초과하는 사용이 필요하다면 Daiso MCP는 오픈 소스이므로 이 저장소를 직접 배포해 이용해 주세요.
+
+<div align="center">
 
 <!-- WORKERS_INVOCATIONS_CHART:END -->
 
@@ -99,7 +117,7 @@
 
 ## AI 앱에서 MCP 연결하기
 
-ChatGPT, Claude, Grok 같은 AI 앱에서 바로 연결해 사용할 수 있습니다.
+ChatGPT, Claude, Home Assistant, Grok 같은 AI 앱에서 바로 연결해 사용할 수 있습니다.
 아래 앱별 가이드에서 먼저 연동한 뒤 검색/재고/영화 조회를 요청하세요.
 
 <br>
@@ -127,6 +145,8 @@ GS25 mcp로 강남 근처 매장과 오감자 재고 알려줘
 세븐일레븐 mcp로 인기 검색어와 카탈로그 요약 알려줘
 강남역 근처 카페 찾아줘
 성수동 근처 브런치 음식점 찾아줘
+강남역 근처 제일 싼 주유소 찾아줘
+오늘 전국 평균 휘발유 가격 알려줘
 메가박스 mcp로 강남점 영화와 잔여 좌석 알려줘
 롯데시네마 mcp로 월드타워 근처 지점과 상영 영화 알려줘
 롯데시네마 mcp로 월드타워 잔여 좌석 알려줘
@@ -137,6 +157,7 @@ CGV mcp로 강남 상영 영화와 시간표 알려줘
 
 - 가격 비교: `콜라 어디가 싸?` → `compare_products`
 - 주변 장소: `강남역 근처 카페 찾아줘` → `places_search_nearby`
+- 주유소/유가: `강남역 근처 제일 싼 주유소 찾아줘` → `opinet_search_stations_around`
 - 브랜드 명시 재고: `다이소 핫식스 재고 찾아줘` → 먼저 다이소에서 검색 후 결과 없을 때만 대안 제안
 - 편의점 재고: `GS25 강남 오감자 재고` → 상품 후보 확인 후 재고 조회
 - 영화 시간표: `오늘 강남 CGV 시간표` → KST 오늘 날짜로 극장 검색 후 시간표 조회
@@ -188,6 +209,19 @@ claude mcp add daiso-mcp https://mcp.aka.page --transport http
 
 <br>
 
+### Home Assistant
+
+> Home Assistant Core 2026.7.1에서 MCP 도구 40개를 모두 정상적으로 불러오는 것을 확인했습니다.
+
+1. Home Assistant에서 **Settings** → **Devices & services**로 이동
+2. **Add Integration**을 선택하고 **Model Context Protocol**을 검색
+3. 서버 URL 입력: `https://mcp.aka.page`
+4. 연동을 마친 뒤 사용할 대화 에이전트가 MCP 도구를 사용하도록 설정
+
+참고: [Home Assistant Model Context Protocol 통합 가이드](https://www.home-assistant.io/integrations/mcp)
+
+<br>
+
 ### ![Grok](https://img.shields.io/badge/Grok-000000?logo=x&logoColor=white)
 
 > 웹 및 모바일 앱 모두 지원
@@ -330,9 +364,9 @@ MCP 도구 응답은 각 서비스의 원본 필드를 유지하면서, 클라
 - `standard.theaters`: 영화관 목록을 `code`, `name`, `address`, `distanceMeters`, `raw` 형태로 정규화합니다.
 - `standard.places`: 음식점/카페 같은 장소 목록을 `name`, `address`, `raw` 중심으로 정규화합니다.
 
-### 키 없는 통합 가격 후보 비교
+### 통합 상품 가격 비교
 
-새 외부 API 키 없이 기존 상품 검색을 묶어 가격 후보를 비교합니다.
+여러 리테일/편의점 상품 검색 결과를 묶어 같은 상품의 판매처별 가격 후보를 비교합니다.
 
 ```bash
 npx daiso compare 콜라 --limit 3 --json
@@ -434,6 +468,51 @@ curl -H "Authorization: Bearer $HEALTH_CHECK_SECRET" \
 
 Better Stack 같은 외부 모니터링에서는 `fail`을 장애 알림 기준으로 보고, `degraded`는 느린 외부 API나 응답 품질 저하를 추적하는 경고 신호로 봅니다.
 
+### 운영 통계
+
+일일 호출 제한으로 차단한 요청의 집계는 인증된 `GET /api/rate-limit/stats`에서 조회합니다. 헬스 체크와 같은 `HEALTH_CHECK_SECRET`을 사용하며, 다음 두 인증 헤더를 모두 지원합니다.
+
+```bash
+curl -H "Authorization: Bearer $HEALTH_CHECK_SECRET" \
+  "https://mcp.aka.page/api/rate-limit/stats"
+
+curl -H "x-health-check-key: $HEALTH_CHECK_SECRET" \
+  "https://mcp.aka.page/api/rate-limit/stats?service=cgv"
+```
+
+쿼리 필터는 `from`, `to`, `service`입니다. `from`과 `to`는 함께 지정하거나 둘 다 생략해야 하며 날짜 형식은 `YYYY-MM-DD`입니다. `service`에는 `oliveyoung`, `cgv`, `cu`, `gs25`, `lottemart`만 사용할 수 있습니다. 날짜를 생략하면 현재 KST 일자를 포함한 최근 7일을 조회합니다. 조회 가능한 보관 범위는 현재 KST 일자와 그 이전 29일이며, 한 번에 KST 달력 날짜 기준 최대 30일을 요청할 수 있습니다.
+
+성공 응답은 전체 합계와 일별·서비스별 차단 요청 수와 고유 차단 주체 수를 제공합니다.
+
+```json
+{
+  "success": true,
+  "data": {
+    "totals": {
+      "blockedRequests": 3,
+      "uniqueIdentities": 2
+    },
+    "daily": [
+      {
+        "day": "2026-07-22",
+        "blockedRequests": 3,
+        "uniqueIdentities": 2
+      }
+    ],
+    "services": [
+      {
+        "day": "2026-07-22",
+        "service": "cgv",
+        "blockedRequests": 3,
+        "uniqueIdentities": 2
+      }
+    ]
+  }
+}
+```
+
+데이터는 30일 동안 보관하며 집계 응답은 원본 호출 주체나 IP를 노출하지 않습니다. Worker가 생성한 `DAILY_RATE_LIMIT_EXCEEDED` 결정 중 원장 커밋에 성공한 경우만 정확한 집계 범위에 포함됩니다. Cloudflare 또는 네트워크 계층의 429와 클라이언트 전송 결과, 연결 종료 결과는 이 범위에 포함되지 않습니다. 원장 쓰기에 실패하면 요청을 fail-open 처리하고 애플리케이션 429를 반환하지 않습니다. 통계는 이 기능의 배포 시점부터 수집하며 이전 429는 소급 집계하지 않습니다.
+
 배포 전 로컬에서 CLI 모드까지 확인할 때는 아래 명령을 사용합니다.
 
 ```bash

package/dist/api/actionsProxy.js

@@ -2,6 +2,9 @@
  * OpenAI Actions용 공통 GET 프록시 정의
  */
 export const ACTION_QUERY_DEFINITIONS = [
+    { action: 'dtryxListCinemas', summary: '디트릭스 극장 목록', targetPath: '/api/dtryx/cinemas' },
+    { action: 'dtryxListNowShowing', summary: '디트릭스 상영작', targetPath: '/api/dtryx/movies' },
+    { action: 'dtryxGetRemainingSeats', summary: '디트릭스 잔여 좌석', targetPath: '/api/dtryx/seats' },
     { action: 'daisoSearchProducts', summary: '다이소 제품 검색', targetPath: '/api/daiso/products' },
     {
         action: 'daisoGetProduct',

package/dist/api/cgvHandlers.js

@@ -1,7 +1,8 @@
 /**
  * CGV GET API 핸들러
  */
-import { fetchCgvMovies, fetchCgvTheaters, fetchCgvTimetable, toYyyymmdd } from '../services/cgv/client.js';
+import { fetchCgvMovies, fetchCgvTheaters, fetchCgvTimetable, toYyyymmdd, } from '../services/cgv/client.js';
+import { isCgvUpstreamUnavailableError } from '../services/cgv/errors.js';
 import { fetchCgvNearbyTheaters, resolveCgvNearestTheater } from '../services/cgv/location.js';
 import { filterAndSortTimetable } from '../services/cgv/timetable.js';
 import { errorResponse, successResponse } from './response.js';
@@ -60,6 +61,9 @@ export async function handleCgvFindTheaters(c) {
         }, { total: sliced.length, pageSize: limit });
     }
     catch (error) {
+        if (isCgvUpstreamUnavailableError(error)) {
+            return errorResponse(c, 'CGV_UPSTREAM_UNAVAILABLE', error.message, 503);
+        }
         const message = error instanceof Error ? error.message : '알 수 없는 오류가 발생했습니다.';
         return errorResponse(c, 'CGV_THEATER_SEARCH_FAILED', message, 500);
     }
@@ -77,7 +81,8 @@ export async function handleCgvSearchMovies(c) {
     const timeoutMs = parseInt(c.req.query('timeoutMs') || '15000');
     try {
         let resolvedTheater = null;
-        if (!theaterCode && (keyword || typeof latitude === 'number' || typeof longitude === 'number')) {
+        if (!theaterCode &&
+            (keyword || typeof latitude === 'number' || typeof longitude === 'number')) {
             const resolved = await resolveCgvNearestTheater({
                 playDate,
                 keyword,
@@ -114,6 +119,9 @@ export async function handleCgvSearchMovies(c) {
         }, { total: movies.length });
     }
     catch (error) {
+        if (isCgvUpstreamUnavailableError(error)) {
+            return errorResponse(c, 'CGV_UPSTREAM_UNAVAILABLE', error.message, 503);
+        }
         const message = error instanceof Error ? error.message : '알 수 없는 오류가 발생했습니다.';
         return errorResponse(c, 'CGV_MOVIE_SEARCH_FAILED', message, 500);
     }
@@ -133,7 +141,8 @@ export async function handleCgvGetTimetable(c) {
     const timeoutMs = parseInt(c.req.query('timeoutMs') || '15000');
     try {
         let resolvedTheater = null;
-        if (!theaterCode && (keyword || typeof latitude === 'number' || typeof longitude === 'number')) {
+        if (!theaterCode &&
+            (keyword || typeof latitude === 'number' || typeof longitude === 'number')) {
             const resolved = await resolveCgvNearestTheater({
                 playDate,
                 keyword,
@@ -178,6 +187,9 @@ export async function handleCgvGetTimetable(c) {
         }, { total: filtered.length, pageSize: limit });
     }
     catch (error) {
+        if (isCgvUpstreamUnavailableError(error)) {
+            return errorResponse(c, 'CGV_UPSTREAM_UNAVAILABLE', error.message, 503);
+        }
         const message = error instanceof Error ? error.message : '알 수 없는 오류가 발생했습니다.';
         return errorResponse(c, 'CGV_TIMETABLE_FETCH_FAILED', message, 500);
     }

package/dist/api/configStatus.js

@@ -9,7 +9,7 @@ export function buildConfigStatus(bindings) {
         },
         zyteApiKey: {
             configured: isConfigured(bindings?.ZYTE_API_KEY),
-            usedBy: ['oliveyoung', 'gs25', 'lottemart', 'cgv'],
+            usedBy: ['oliveyoung', 'gs25', 'cu', 'seveneleven', 'lottemart', 'cgv'],
         },
         naverLocalSearch: {
             configured: isConfigured(bindings?.NAVER_CLIENT_ID) && isConfigured(bindings?.NAVER_CLIENT_SECRET),

package/dist/api/dtryxHandlers.js

@@ -0,0 +1,113 @@
+/**
+ * 디트릭스 GET API 핸들러
+ */
+import { resolveDtryxCinemas } from '../services/dtryx/location.js';
+import { DTRYX_INVALID_INPUT, hasInvalidDtryxOptions } from '../services/dtryx/validation.js';
+import { fetchDtryxNowShowing, fetchDtryxPlayDates, fetchDtryxTimetable, toYyyymmdd, } from '../services/dtryx/client.js';
+import { errorResponse, successResponse } from './response.js';
+export async function handleDtryxListCinemas(c) {
+    const keyword = c.req.query('keyword') || undefined;
+    const region = c.req.query('region') || undefined;
+    const brandCode = c.req.query('brandCode') || undefined;
+    const limit = Number(c.req.query('limit') ?? '50');
+    if (hasInvalidDtryxOptions({ limit })) {
+        return errorResponse(c, 'DTRYX_INVALID_INPUT', DTRYX_INVALID_INPUT, 400);
+    }
+    const cinemas = resolveDtryxCinemas({ keyword, region, brandCode }).slice(0, limit);
+    return successResponse(c, {
+        filters: {
+            keyword: keyword || null,
+            region: region || null,
+            brandCode: brandCode || null,
+            limit,
+        },
+        count: cinemas.length,
+        cinemas,
+    }, { total: cinemas.length, pageSize: limit });
+}
+export async function handleDtryxListNowShowing(c) {
+    const cinemaCode = c.req.query('cinemaCode') || undefined;
+    const keyword = c.req.query('keyword') || undefined;
+    const brandCode = c.req.query('brandCode') || undefined;
+    const includePlayDates = c.req.query('includePlayDates') === 'true';
+    const timeoutMs = Number(c.req.query('timeoutMs') ?? '15000');
+    if (hasInvalidDtryxOptions({ timeoutMs })) {
+        return errorResponse(c, 'DTRYX_INVALID_INPUT', DTRYX_INVALID_INPUT, 400);
+    }
+    const cinema = cinemaCode || keyword ? resolveDtryxCinemas({ cinemaCode, keyword, brandCode })[0] : undefined;
+    if (!cinema) {
+        return errorResponse(c, 'DTRYX_CINEMA_NOT_FOUND', '극장을 찾을 수 없습니다. cinemaCode 또는 keyword 를 확인하세요.', 404);
+    }
+    try {
+        const request = {
+            brandCode: cinema.brandCode,
+            cinemaCode: cinema.cinemaCode,
+            timeout: timeoutMs,
+        };
+        const [movies, playDates] = await Promise.all([
+            fetchDtryxNowShowing(request),
+            includePlayDates ? fetchDtryxPlayDates(request) : Promise.resolve([]),
+        ]);
+        return successResponse(c, {
+            cinema,
+            count: movies.length,
+            movies,
+            playDates: includePlayDates ? playDates : undefined,
+        }, { total: movies.length });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : '알 수 없는 오류가 발생했습니다.';
+        return errorResponse(c, 'DTRYX_NOW_SHOWING_FAILED', message, 500);
+    }
+}
+export async function handleDtryxGetRemainingSeats(c) {
+    const playDate = c.req.query('playDate') || toYyyymmdd();
+    const cinemaCode = c.req.query('cinemaCode') || undefined;
+    const keyword = c.req.query('keyword') || undefined;
+    const brandCode = c.req.query('brandCode') || undefined;
+    const movieName = c.req.query('movieName') || undefined;
+    const region = c.req.query('region') || undefined;
+    const limit = Number(c.req.query('limit') ?? '50');
+    const timeoutMs = Number(c.req.query('timeoutMs') ?? '15000');
+    if (hasInvalidDtryxOptions({ limit, timeoutMs, playDate })) {
+        return errorResponse(c, 'DTRYX_INVALID_INPUT', DTRYX_INVALID_INPUT, 400);
+    }
+    const cinemas = resolveDtryxCinemas({ cinemaCode, keyword, brandCode, region });
+    if (cinemas.length === 0) {
+        return errorResponse(c, 'DTRYX_CINEMA_NOT_FOUND', '극장을 찾을 수 없습니다. cinemaCode 또는 keyword 를 확인하세요.', 404);
+    }
+    // Promise.allSettled 로 극장별 실패를 흡수하므로 여기서 예외가 전파되지 않습니다.
+    const settled = await Promise.allSettled(cinemas.map((cinema) => fetchDtryxTimetable({
+        brandCode: cinema.brandCode,
+        cinemaCode: cinema.cinemaCode,
+        playDate,
+        timeout: timeoutMs,
+    })));
+    const failedCinemas = cinemas
+        .filter((_, index) => settled[index]?.status === 'rejected')
+        .map((cinema) => cinema.cinemaName || cinema.cinemaCode);
+    if (failedCinemas.length === cinemas.length) {
+        return errorResponse(c, 'DTRYX_SEATS_FAILED', `모든 극장 조회에 실패했습니다: ${failedCinemas.join(', ')}`, 503);
+    }
+    const normalize = (value) => value.replace(/\s+/g, '').toLowerCase();
+    const showtimes = settled
+        .flatMap((result) => (result.status === 'fulfilled' ? result.value : []))
+        .filter((item) => (movieName ? normalize(item.movieName).includes(normalize(movieName)) : true))
+        .sort((a, b) => a.startTime === b.startTime
+        ? a.cinemaName.localeCompare(b.cinemaName)
+        : a.startTime.localeCompare(b.startTime))
+        .slice(0, limit);
+    return successResponse(c, {
+        playDate,
+        filters: {
+            cinemaCode: cinemaCode || null,
+            keyword: keyword || null,
+            region: region || null,
+            movieName: movieName || null,
+        },
+        searchedCinemaCount: cinemas.length,
+        failedCinemas,
+        count: showtimes.length,
+        showtimes,
+    }, { total: showtimes.length, pageSize: limit });
+}

package/dist/api/emart24Handlers.js

@@ -15,6 +15,8 @@ export async function handleEmart24FindStores(c) {
     const service24h = c.req.query('service24h') === 'true';
     const page = parseInt(c.req.query('page') || '1', 10);
     const limit = parseInt(c.req.query('limit') || '20', 10);
+    const parsedTimeoutMs = parseInt(c.req.query('timeoutMs') || '15000', 10);
+    const timeoutMs = Number.isFinite(parsedTimeoutMs) && parsedTimeoutMs > 0 ? parsedTimeoutMs : 15000;
     const rawLat = c.req.query('lat');
     const rawLng = c.req.query('lng');
     const parsedLat = rawLat ? parseFloat(rawLat) : undefined;
@@ -29,7 +31,7 @@ export async function handleEmart24FindStores(c) {
             page,
             service24h,
         }, {
-            timeout: 15000,
+            timeout: timeoutMs,
         });
         const stores = result.stores
             .map((store) => {
@@ -72,6 +74,8 @@ export async function handleEmart24SearchProducts(c) {
     const pageSize = parseInt(c.req.query('pageSize') || '10', 10);
     const sortType = c.req.query('sortType') || 'SALE';
     const saleProductYn = c.req.query('saleProductYn') || 'N';
+    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)를 입력해주세요.');
     }
@@ -83,7 +87,7 @@ export async function handleEmart24SearchProducts(c) {
             sortType,
             saleProductYn,
         }, {
-            timeout: 15000,
+            timeout: timeoutMs,
         });
         return successResponse(c, {
             keyword,

package/dist/api/gs25Handlers.js

@@ -4,6 +4,7 @@
 /* c8 ignore start */
 import { errorResponse, successResponse } from './response.js';
 import { attachDistanceToGs25Stores, fetchGs25SearchProducts, fetchGs25Stores, fetchGs25WebStores, filterGs25StoresByKeyword, geocodeGs25Address, selectGs25StoresForKeyword, sortGs25Stores, } from '../services/gs25/client.js';
+import { isGs25UpstreamUnavailableError } from '../services/gs25/errors.js';
 const GS25_FALLBACK_STORE_LOOKUP_ITEM_CODE = '8801117752804';
 /**
  * GS25 매장 검색 API 핸들러
@@ -33,6 +34,7 @@ export async function handleGs25FindStores(c) {
                 geocodeUsed = true;
             }
         }
+        let fallbackUsed = false;
         let storeResult = await fetchGs25Stores({
             serviceCode,
             latitude,
@@ -40,9 +42,15 @@ export async function handleGs25FindStores(c) {
         }, {
             timeout: 20000,
             zyteApiKey: c.env?.ZYTE_API_KEY,
+            apiKey: c.env?.GS25_API_KEY,
+        }).catch(async (error) => {
+            if (!isGs25UpstreamUnavailableError(error) || keyword.trim().length === 0)
+                throw error;
+            const webStoreResult = await fetchGs25WebStores(keyword, { timeout: 20000 });
+            fallbackUsed = true;
+            return { ...webStoreResult, cacheHit: false };
         });
-        let fallbackUsed = false;
-        if (storeResult.stores.length === 0 &&
+        if (!fallbackUsed && storeResult.stores.length === 0 &&
             typeof latitude === 'number' &&
             typeof longitude === 'number') {
             try {
@@ -56,6 +64,7 @@ export async function handleGs25FindStores(c) {
                 }, {
                     timeout: 20000,
                     zyteApiKey: c.env?.ZYTE_API_KEY,
+                    apiKey: c.env?.GS25_API_KEY,
                 });
                 if (fallbackResult.stores.length > 0) {
                     storeResult = fallbackResult;
@@ -66,23 +75,10 @@ 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;
-            }
+        if (!fallbackUsed && storeResult.stores.length === 0 && keyword.trim().length > 0) {
+            const webStoreResult = await fetchGs25WebStores(keyword, { timeout: 20000 });
+            storeResult = { ...webStoreResult, cacheHit: false };
+            fallbackUsed = true;
         }
         const selected = selectGs25StoresForKeyword(storeResult.stores, keyword, {
             relaxWhenEmpty: typeof latitude === 'number' && typeof longitude === 'number',
@@ -185,6 +181,7 @@ export async function handleGs25CheckInventory(c) {
                 }, {
                     timeout: 20000,
                     zyteApiKey: c.env?.ZYTE_API_KEY,
+                    apiKey: c.env?.GS25_API_KEY,
                 });
                 const firstAddress = filterGs25StoresByKeyword(baseStores.stores, storeKeyword).find((store) => store.address.trim().length > 0)?.address || '';
                 if (firstAddress.length > 0) {
@@ -216,6 +213,7 @@ export async function handleGs25CheckInventory(c) {
             }, {
                 timeout: 20000,
                 zyteApiKey: c.env?.ZYTE_API_KEY,
+                apiKey: c.env?.GS25_API_KEY,
             });
         }
         else {
@@ -237,6 +235,7 @@ export async function handleGs25CheckInventory(c) {
                 }, {
                     timeout: 20000,
                     zyteApiKey: c.env?.ZYTE_API_KEY,
+                    apiKey: c.env?.GS25_API_KEY,
                 });
             }
             else {
@@ -250,6 +249,7 @@ export async function handleGs25CheckInventory(c) {
                 }, {
                     timeout: 20000,
                     zyteApiKey: c.env?.ZYTE_API_KEY,
+                    apiKey: c.env?.GS25_API_KEY,
                 });
             }
         }
@@ -295,6 +295,9 @@ export async function handleGs25CheckInventory(c) {
         });
     }
     catch (error) {
+        if (isGs25UpstreamUnavailableError(error)) {
+            return errorResponse(c, 'GS25_UPSTREAM_UNAVAILABLE', error.message, 503);
+        }
         const message = error instanceof Error ? error.message : '알 수 없는 오류가 발생했습니다.';
         return errorResponse(c, 'GS25_INVENTORY_CHECK_FAILED', message, 500);
     }

package/dist/api/handlers.js

@@ -229,6 +229,7 @@ export async function handleCuCheckInventory(c) {
             searchSort,
         }, {
             timeout: 15000,
+            apiKey: c.env?.ZYTE_API_KEY,
         });
         const firstStockItem = stockResult.items.find((item) => item.itemCode.trim().length > 0) || null;
         const hasInputLocation = typeof lat === 'number' && typeof lng === 'number';
@@ -300,6 +301,8 @@ export async function handleCuCheckInventory(c) {
                 stores: storeResult.stores.slice(0, storeLimit),
             },
             inventory: {
+                available: stockResult.available,
+                unavailableReason: stockResult.unavailableReason,
                 totalCount: stockResult.totalCount,
                 spellModifyYn: stockResult.spellModifyYn,
                 items: stockResult.items,

package/dist/api/healthCheckDefinitions.js

@@ -6,7 +6,23 @@ export const GS25_CLOUDFRONT_403_PATTERNS = [
     '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: 'dtryx.movies',
+        service: 'dtryx',
+        target: 'movies',
+        mode: 'deep',
+        path: '/api/dtryx/movies?cinemaCode=000067',
+        collectionKey: 'movies',
+        requiredFields: ['movieCode', 'movieName'],
+    },
     {
         id: 'cli.contract',
         service: 'cli',
@@ -41,6 +57,17 @@ export const HEALTH_CHECKS = [
         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: 'emart24.stores',
+        service: 'emart24',
+        target: 'stores',
+        mode: 'quick',
+        path: '/api/emart24/stores?keyword=%EA%B0%95%EB%82%A8&limit=1',
+        collectionKey: 'stores',
+        requiredFields: ['storeCode', 'storeName', 'name'],
+        degradedFailurePatterns: EMART24_UPSTREAM_403_PATTERNS,
     },
     {
         id: 'gs25.products',
@@ -69,6 +96,26 @@ export const HEALTH_CHECKS = [
         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: 'seveneleven.stores',
+        service: 'seveneleven',
+        target: 'stores',
+        mode: 'quick',
+        path: '/api/seveneleven/stores?keyword=%EA%B0%95%EB%82%A8&limit=1',
+        collectionKey: 'stores',
+        requiredFields: ['storeCode', 'storeName', 'name'],
+        degradedFailurePatterns: SEVENELEVEN_UPSTREAM_403_PATTERNS,
+    },
+    {
+        id: 'seveneleven.popwords',
+        service: 'seveneleven',
+        target: 'popwords',
+        mode: 'quick',
+        path: '/api/seveneleven/popwords?label=home',
+        degradedFailurePatterns: SEVENELEVEN_UPSTREAM_403_PATTERNS,
+        allowEmpty: true,
     },
     {
         id: 'lottemart.products',
@@ -87,7 +134,6 @@ export const HEALTH_CHECKS = [
         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',
@@ -124,6 +170,7 @@ export const HEALTH_CHECKS = [
         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',
@@ -131,8 +178,9 @@ export const HEALTH_CHECKS = [
         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'],
+        collectionKey: 'stores',
+        requiredFields: ['storeCode', 'storeName', 'name'],
+        degradedFailurePatterns: EMART24_UPSTREAM_403_PATTERNS,
     },
     {
         id: 'gs25.inventory',
@@ -140,8 +188,8 @@ export const HEALTH_CHECKS = [
         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'],
+        collectionKey: 'inventoryStores',
+        requiredFields: ['storeCode', 'storeName', 'name'],
         degradedFailurePatterns: [
             '401 Unauthorized',
             '인증키가 제공되지 않음',
@@ -154,8 +202,9 @@ export const HEALTH_CHECKS = [
         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'],
+        collectionKey: 'inventoryStores',
+        requiredFields: ['storeCode', 'storeName', 'name'],
+        degradedFailurePatterns: SEVENELEVEN_UPSTREAM_403_PATTERNS,
     },
     {
         id: 'oliveyoung.inventory',
@@ -165,6 +214,5 @@ export const HEALTH_CHECKS = [
         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,
     },
 ];