daiso 1.0.3 → 1.0.5

package/dist/api/megaboxHandlers.js

@@ -1,63 +1,42 @@
 /**
  * 메가박스 GET API 핸들러
  */
-import { fetchMegaboxBookingList, fetchMegaboxTheaterInfo, toYyyymmdd, } from '../services/megabox/client.js';
+import { fetchMegaboxBookingList, toYyyymmdd } from '../services/megabox/client.js';
+import { fetchMegaboxNearbyTheaters, resolveMegaboxNearestTheater } from '../services/megabox/location.js';
 import { errorResponse, successResponse } from './response.js';
-function calculateDistanceKm(lat1, lng1, lat2, lng2) {
-    const toRad = (deg) => (deg * Math.PI) / 180;
-    const dLat = toRad(lat2 - lat1);
-    const dLng = toRad(lng2 - lng1);
-    const a = Math.sin(dLat / 2) * Math.sin(dLat / 2) +
-        Math.cos(toRad(lat1)) * Math.cos(toRad(lat2)) * Math.sin(dLng / 2) * Math.sin(dLng / 2);
-    const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
-    return 6371 * c;
+function parseOptionalNumber(value) {
+    if (!value) {
+        return undefined;
+    }
+    const parsed = Number.parseFloat(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
 }
 /**
  * 메가박스 주변 지점 조회 API 핸들러
  * GET /api/megabox/theaters?lat={위도}&lng={경도}&playDate={YYYYMMDD}&areaCode={지역코드}
  */
 export async function handleMegaboxFindNearbyTheaters(c) {
-    const lat = parseFloat(c.req.query('lat') || '37.5665');
-    const lng = parseFloat(c.req.query('lng') || '126.978');
+    const keyword = c.req.query('keyword') || undefined;
+    const lat = parseOptionalNumber(c.req.query('lat'));
+    const lng = parseOptionalNumber(c.req.query('lng'));
     const playDate = c.req.query('playDate') || toYyyymmdd();
-    const areaCode = c.req.query('areaCode') || '11';
+    const areaCode = c.req.query('areaCode') || undefined;
     const limit = parseInt(c.req.query('limit') || '10');
     const timeoutMs = parseInt(c.req.query('timeoutMs') || '15000');
     try {
-        const { theaters } = await fetchMegaboxBookingList({
+        const result = await fetchMegaboxNearbyTheaters({
+            keyword,
+            latitude: lat,
+            longitude: lng,
             playDate,
             areaCode,
+            limit,
+            timeout: timeoutMs,
+        }, {
+            googleMapsApiKey: c.env?.GOOGLE_MAPS_API_KEY,
             timeout: timeoutMs,
         });
-        const infoResults = await Promise.allSettled(theaters.map((theater) => fetchMegaboxTheaterInfo(theater.theaterId, timeoutMs)));
-        const merged = theaters
-            .map((theater, index) => {
-            const infoResult = infoResults[index];
-            if (infoResult.status !== 'fulfilled') {
-                return null;
-            }
-            if (infoResult.value.latitude === null || infoResult.value.longitude === null) {
-                return null;
-            }
-            const distanceKm = calculateDistanceKm(lat, lng, infoResult.value.latitude, infoResult.value.longitude);
-            return {
-                theaterId: theater.theaterId,
-                theaterName: theater.theaterName,
-                address: infoResult.value.address,
-                latitude: infoResult.value.latitude,
-                longitude: infoResult.value.longitude,
-                distanceKm: Number(distanceKm.toFixed(2)),
-            };
-        })
-            .filter((theater) => theater !== null)
-            .sort((a, b) => a.distanceKm - b.distanceKm)
-            .slice(0, limit);
-        return successResponse(c, {
-            location: { latitude: lat, longitude: lng },
-            playDate,
-            areaCode,
-            theaters: merged,
-        }, { total: merged.length, pageSize: limit });
+        return successResponse(c, result, { total: result.count, pageSize: limit });
     }
     catch (error) {
         const message = error instanceof Error ? error.message : '알 수 없는 오류가 발생했습니다.';
@@ -70,16 +49,38 @@ export async function handleMegaboxFindNearbyTheaters(c) {
  */
 export async function handleMegaboxListNowShowing(c) {
     const playDate = c.req.query('playDate') || toYyyymmdd();
-    const theaterId = c.req.query('theaterId') || undefined;
+    const keyword = c.req.query('keyword') || undefined;
+    const lat = parseOptionalNumber(c.req.query('lat'));
+    const lng = parseOptionalNumber(c.req.query('lng'));
+    let theaterId = c.req.query('theaterId') || undefined;
     const movieId = c.req.query('movieId') || undefined;
-    const areaCode = c.req.query('areaCode') || '11';
+    const areaCode = c.req.query('areaCode') || undefined;
     const timeoutMs = parseInt(c.req.query('timeoutMs') || '15000');
     try {
+        let resolvedTheater = null;
+        let resolvedLocation = null;
+        if (!theaterId && (keyword || typeof lat === 'number' || typeof lng === 'number')) {
+            const resolved = await resolveMegaboxNearestTheater({
+                keyword,
+                latitude: lat,
+                longitude: lng,
+                areaCode,
+                playDate,
+                timeout: timeoutMs,
+            }, {
+                googleMapsApiKey: c.env?.GOOGLE_MAPS_API_KEY,
+                timeout: timeoutMs,
+            });
+            theaterId = resolved.theater?.theaterId;
+            resolvedTheater = resolved.theater;
+            resolvedLocation = resolved.location;
+        }
+        const resolvedAreaCode = resolvedLocation?.areaCode || areaCode || '11';
         const result = await fetchMegaboxBookingList({
             playDate,
             theaterId,
             movieId,
-            areaCode,
+            areaCode: resolvedAreaCode,
             timeout: timeoutMs,
         });
         return successResponse(c, {
@@ -87,8 +88,12 @@ export async function handleMegaboxListNowShowing(c) {
             filters: {
                 theaterId: theaterId || null,
                 movieId: movieId || null,
-                areaCode,
+                keyword: keyword || null,
+                latitude: lat ?? null,
+                longitude: lng ?? null,
+                areaCode: resolvedAreaCode,
             },
+            resolvedTheater,
             theaters: result.theaters,
             movies: result.movies,
             showtimes: result.showtimes,
@@ -105,17 +110,39 @@ export async function handleMegaboxListNowShowing(c) {
  */
 export async function handleMegaboxGetRemainingSeats(c) {
     const playDate = c.req.query('playDate') || toYyyymmdd();
-    const theaterId = c.req.query('theaterId') || undefined;
+    const keyword = c.req.query('keyword') || undefined;
+    const lat = parseOptionalNumber(c.req.query('lat'));
+    const lng = parseOptionalNumber(c.req.query('lng'));
+    let theaterId = c.req.query('theaterId') || undefined;
     const movieId = c.req.query('movieId') || undefined;
-    const areaCode = c.req.query('areaCode') || '11';
+    const areaCode = c.req.query('areaCode') || undefined;
     const limit = parseInt(c.req.query('limit') || '50');
     const timeoutMs = parseInt(c.req.query('timeoutMs') || '15000');
     try {
+        let resolvedTheater = null;
+        let resolvedLocation = null;
+        if (!theaterId && (keyword || typeof lat === 'number' || typeof lng === 'number')) {
+            const resolved = await resolveMegaboxNearestTheater({
+                keyword,
+                latitude: lat,
+                longitude: lng,
+                areaCode,
+                playDate,
+                timeout: timeoutMs,
+            }, {
+                googleMapsApiKey: c.env?.GOOGLE_MAPS_API_KEY,
+                timeout: timeoutMs,
+            });
+            theaterId = resolved.theater?.theaterId;
+            resolvedTheater = resolved.theater;
+            resolvedLocation = resolved.location;
+        }
+        const resolvedAreaCode = resolvedLocation?.areaCode || areaCode || '11';
         const { showtimes } = await fetchMegaboxBookingList({
             playDate,
             theaterId,
             movieId,
-            areaCode,
+            areaCode: resolvedAreaCode,
             timeout: timeoutMs,
         });
         const seats = showtimes
@@ -133,8 +160,12 @@ export async function handleMegaboxGetRemainingSeats(c) {
             filters: {
                 theaterId: theaterId || null,
                 movieId: movieId || null,
-                areaCode,
+                keyword: keyword || null,
+                latitude: lat ?? null,
+                longitude: lng ?? null,
+                areaCode: resolvedAreaCode,
             },
+            resolvedTheater,
             seats,
         }, { total: seats.length, pageSize: limit });
     }

package/dist/api/routes/cuRoutes.js

@@ -0,0 +1,17 @@
+/**
+ * CU GET API 라우트 등록
+ */
+import { withEdgeCache } from '../../utils/cache.js';
+import { handleCuFindStores, handleCuCheckInventory } from '../handlers.js';
+export function registerCuRoutes(app) {
+    app.get('/api/cu/stores', async (c) => withEdgeCache(c.req.url, {
+        ttlSeconds: 60 * 60 * 24,
+        staleWhileRevalidateSeconds: 60 * 5,
+        keyPrefix: 'cu-stores-v1',
+    }, () => handleCuFindStores(c)));
+    app.get('/api/cu/inventory', async (c) => withEdgeCache(c.req.url, {
+        ttlSeconds: 60 * 10,
+        staleWhileRevalidateSeconds: 60,
+        keyPrefix: 'cu-inventory-v1',
+    }, () => handleCuCheckInventory(c)));
+}

package/dist/api/routes/daisoRoutes.js

@@ -2,7 +2,7 @@
  * 다이소 GET API 라우트 등록
  */
 import { withEdgeCache } from '../../utils/cache.js';
-import { handleSearchProducts, handleGetProduct, handleFindStores, handleCheckInventory, } from '../handlers.js';
+import { handleSearchProducts, handleGetProduct, handleFindStores, handleCheckInventory, handleGetDisplayLocation, } from '../handlers.js';
 export function registerDaisoRoutes(app) {
     app.get('/api/daiso/products', async (c) => withEdgeCache(c.req.url, {
         ttlSeconds: 60 * 30,
@@ -24,4 +24,9 @@ export function registerDaisoRoutes(app) {
         staleWhileRevalidateSeconds: 60,
         keyPrefix: 'daiso-inventory-v1',
     }, () => handleCheckInventory(c)));
+    app.get('/api/daiso/display-location', async (c) => withEdgeCache(c.req.url, {
+        ttlSeconds: 60 * 10,
+        staleWhileRevalidateSeconds: 60,
+        keyPrefix: 'daiso-display-location-v1',
+    }, () => handleGetDisplayLocation(c)));
 }

package/dist/api/routes/emart24Routes.js

@@ -0,0 +1,22 @@
+/**
+ * 이마트24 GET API 라우트 등록
+ */
+import { withEdgeCache } from '../../utils/cache.js';
+import { handleEmart24CheckInventory, handleEmart24FindStores, handleEmart24SearchProducts, } from '../emart24Handlers.js';
+export function registerEmart24Routes(app) {
+    app.get('/api/emart24/stores', async (c) => withEdgeCache(c.req.url, {
+        ttlSeconds: 60 * 30,
+        staleWhileRevalidateSeconds: 60 * 3,
+        keyPrefix: 'emart24-stores-v1',
+    }, () => handleEmart24FindStores(c)));
+    app.get('/api/emart24/products', async (c) => withEdgeCache(c.req.url, {
+        ttlSeconds: 60 * 10,
+        staleWhileRevalidateSeconds: 60,
+        keyPrefix: 'emart24-products-v1',
+    }, () => handleEmart24SearchProducts(c)));
+    app.get('/api/emart24/inventory', async (c) => withEdgeCache(c.req.url, {
+        ttlSeconds: 60 * 5,
+        staleWhileRevalidateSeconds: 60,
+        keyPrefix: 'emart24-inventory-v1',
+    }, () => handleEmart24CheckInventory(c)));
+}

package/dist/api/routes/gs25Routes.js

@@ -0,0 +1,22 @@
+/**
+ * GS25 GET API 라우트 등록
+ */
+import { withEdgeCache } from '../../utils/cache.js';
+import { handleGs25CheckInventory, handleGs25FindStores, handleGs25SearchProducts, } from '../gs25Handlers.js';
+export function registerGs25Routes(app) {
+    app.get('/api/gs25/stores', async (c) => withEdgeCache(c.req.url, {
+        ttlSeconds: 60 * 10,
+        staleWhileRevalidateSeconds: 60,
+        keyPrefix: 'gs25-stores-v1',
+    }, () => handleGs25FindStores(c)));
+    app.get('/api/gs25/products', async (c) => withEdgeCache(c.req.url, {
+        ttlSeconds: 60 * 3,
+        staleWhileRevalidateSeconds: 60,
+        keyPrefix: 'gs25-products-v1',
+    }, () => handleGs25SearchProducts(c)));
+    app.get('/api/gs25/inventory', async (c) => withEdgeCache(c.req.url, {
+        ttlSeconds: 60 * 2,
+        staleWhileRevalidateSeconds: 30,
+        keyPrefix: 'gs25-inventory-v1',
+    }, () => handleGs25CheckInventory(c)));
+}

package/dist/api/routes/healthRoutes.js

@@ -0,0 +1,44 @@
+/**
+ * 운영용 상세 헬스 체크 라우트
+ */
+import { errorResponse } from '../response.js';
+import { runHealthChecks } from '../healthChecks.js';
+function parseBoolean(value) {
+    const normalized = (value || '').trim().toLowerCase();
+    return normalized === 'true' || normalized === '1' || normalized === 'y';
+}
+function readHealthCheckToken(headers) {
+    const authorization = headers.get('Authorization') || '';
+    if (authorization.toLowerCase().startsWith('bearer ')) {
+        return authorization.slice('bearer '.length).trim();
+    }
+    return (headers.get('x-health-check-key') || '').trim();
+}
+export function registerHealthRoutes(app) {
+    app.get('/api/health/checks', async (c) => {
+        const secret = c.env?.HEALTH_CHECK_SECRET?.trim();
+        if (!secret) {
+            return errorResponse(c, 'HEALTH_CHECK_SECRET_NOT_CONFIGURED', 'HEALTH_CHECK_SECRET이 설정되어 있지 않습니다.', 503);
+        }
+        if (readHealthCheckToken(c.req.raw.headers) !== secret) {
+            return errorResponse(c, 'UNAUTHORIZED_HEALTH_CHECK', '유효한 헬스 체크 시크릿 키가 필요합니다.', 401);
+        }
+        const mode = c.req.query('mode') === 'deep' ? 'deep' : 'quick';
+        const timeoutMs = Number.parseInt(c.req.query('timeoutMs') || '3000', 10);
+        const baseUrl = c.env?.HEALTH_CHECK_BASE_URL?.trim() || new URL(c.req.url).origin;
+        const fetchImpl = c.env?.HEALTH_CHECK_BASE_URL && c.env?.HEALTH_CHECK_TRANSPORT !== 'network'
+            ? async (input, init) => app.fetch(new Request(input, init), c.env)
+            : undefined;
+        const result = await runHealthChecks({
+            baseUrl,
+            service: c.req.query('service') || undefined,
+            check: c.req.query('check') || undefined,
+            mode,
+            timeoutMs,
+            includeSamples: parseBoolean(c.req.query('includeSamples')),
+            fresh: parseBoolean(c.req.query('fresh')),
+            fetchImpl,
+        });
+        return c.json(result);
+    });
+}

package/dist/api/routes/lottecinemaRoutes.js

@@ -0,0 +1,22 @@
+/**
+ * 롯데시네마 GET API 라우트 등록
+ */
+import { withEdgeCache } from '../../utils/cache.js';
+import { handleLotteCinemaFindNearbyTheaters, handleLotteCinemaGetRemainingSeats, handleLotteCinemaListNowShowing, } from '../lottecinemaHandlers.js';
+export function registerLotteCinemaRoutes(app) {
+    app.get('/api/lottecinema/theaters', async (c) => withEdgeCache(c.req.url, {
+        ttlSeconds: 60 * 60 * 24,
+        staleWhileRevalidateSeconds: 60 * 5,
+        keyPrefix: 'lottecinema-theaters-v1',
+    }, () => handleLotteCinemaFindNearbyTheaters(c)));
+    app.get('/api/lottecinema/movies', async (c) => withEdgeCache(c.req.url, {
+        ttlSeconds: 60 * 10,
+        staleWhileRevalidateSeconds: 60,
+        keyPrefix: 'lottecinema-movies-v1',
+    }, () => handleLotteCinemaListNowShowing(c)));
+    app.get('/api/lottecinema/seats', async (c) => withEdgeCache(c.req.url, {
+        ttlSeconds: 60 * 3,
+        staleWhileRevalidateSeconds: 30,
+        keyPrefix: 'lottecinema-seats-v1',
+    }, () => handleLotteCinemaGetRemainingSeats(c)));
+}

package/dist/api/routes/lottemartRoutes.js

@@ -0,0 +1,18 @@
+/**
+ * 롯데마트 GET API 라우트 등록
+ */
+import { withEdgeCache } from '../../utils/cache.js';
+import { handleLotteMartDebug, handleLotteMartFindStores, handleLotteMartSearchProducts } from '../lottemartHandlers.js';
+export function registerLotteMartRoutes(app) {
+    app.get('/api/lottemart/stores', async (c) => withEdgeCache(c.req.url, {
+        ttlSeconds: 60 * 30,
+        staleWhileRevalidateSeconds: 60 * 3,
+        keyPrefix: 'lottemart-stores-v1',
+    }, () => handleLotteMartFindStores(c)));
+    app.get('/api/lottemart/products', async (c) => withEdgeCache(c.req.url, {
+        ttlSeconds: 60 * 5,
+        staleWhileRevalidateSeconds: 60,
+        keyPrefix: 'lottemart-products-v1',
+    }, () => handleLotteMartSearchProducts(c)));
+    app.get('/api/lottemart/debug', (c) => handleLotteMartDebug(c));
+}

package/dist/api/routes/oliveyoungRoutes.js

@@ -2,8 +2,13 @@
  * 올리브영 GET API 라우트 등록
  */
 import { withEdgeCache } from '../../utils/cache.js';
-import { handleOliveyoungFindStores, handleOliveyoungCheckInventory } from '../handlers.js';
+import { handleOliveyoungFindStores, handleOliveyoungCheckInventory, handleOliveyoungSearchProducts, } from '../handlers.js';
 export function registerOliveyoungRoutes(app) {
+    app.get('/api/oliveyoung/products', async (c) => withEdgeCache(c.req.url, {
+        ttlSeconds: 60 * 5,
+        staleWhileRevalidateSeconds: 60,
+        keyPrefix: 'oliveyoung-products-v1',
+    }, () => handleOliveyoungSearchProducts(c)));
     app.get('/api/oliveyoung/stores', async (c) => withEdgeCache(c.req.url, {
         ttlSeconds: 60 * 60 * 24,
         staleWhileRevalidateSeconds: 60 * 5,

package/dist/api/routes/sevenelevenRoutes.js

@@ -0,0 +1,32 @@
+/**
+ * 세븐일레븐 GET API 라우트 등록
+ */
+import { withEdgeCache } from '../../utils/cache.js';
+import { handleSevenElevenCheckInventory, handleSevenElevenGetCatalogSnapshot, handleSevenElevenGetSearchPopwords, handleSevenElevenSearchStores, handleSevenElevenSearchProducts, } from '../sevenelevenHandlers.js';
+export function registerSevenElevenRoutes(app) {
+    app.get('/api/seveneleven/products', async (c) => withEdgeCache(c.req.url, {
+        ttlSeconds: 60 * 3,
+        staleWhileRevalidateSeconds: 60,
+        keyPrefix: 'seveneleven-products-v1',
+    }, () => handleSevenElevenSearchProducts(c)));
+    app.get('/api/seveneleven/stores', async (c) => withEdgeCache(c.req.url, {
+        ttlSeconds: 60 * 3,
+        staleWhileRevalidateSeconds: 60,
+        keyPrefix: 'seveneleven-stores-v1',
+    }, () => handleSevenElevenSearchStores(c)));
+    app.get('/api/seveneleven/inventory', async (c) => withEdgeCache(c.req.url, {
+        ttlSeconds: 60 * 10,
+        staleWhileRevalidateSeconds: 60,
+        keyPrefix: 'seveneleven-inventory-v1',
+    }, () => handleSevenElevenCheckInventory(c)));
+    app.get('/api/seveneleven/popwords', async (c) => withEdgeCache(c.req.url, {
+        ttlSeconds: 60 * 5,
+        staleWhileRevalidateSeconds: 60,
+        keyPrefix: 'seveneleven-popwords-v1',
+    }, () => handleSevenElevenGetSearchPopwords(c)));
+    app.get('/api/seveneleven/catalog', async (c) => withEdgeCache(c.req.url, {
+        ttlSeconds: 60 * 5,
+        staleWhileRevalidateSeconds: 60,
+        keyPrefix: 'seveneleven-catalog-v1',
+    }, () => handleSevenElevenGetCatalogSnapshot(c)));
+}

package/dist/api/sevenelevenHandlers.js

@@ -0,0 +1,200 @@
+/**
+ * 세븐일레븐 GET API 핸들러
+ */
+/* c8 ignore start */
+import { errorResponse, successResponse } from './response.js';
+import { fetchSevenElevenStoresByKeyword, fetchSevenElevenCatalogSnapshot, fetchSevenElevenSearchPopwords, searchSevenElevenProducts, } from '../services/seveneleven/client.js';
+import { checkSevenElevenInventory } from '../services/seveneleven/inventory.js';
+function parseBoolean(value, defaultValue) {
+    if (typeof value !== 'string') {
+        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/seveneleven/products?query={검색어}&page={페이지}&size={개수}&sort={정렬}
+ */
+export async function handleSevenElevenSearchProducts(c) {
+    const query = c.req.query('query') || '';
+    const page = parseInt(c.req.query('page') || '1', 10);
+    const size = parseInt(c.req.query('size') || '20', 10);
+    const sort = c.req.query('sort') || 'recommend';
+    if (query.trim().length === 0) {
+        return errorResponse(c, 'MISSING_QUERY', '검색어(query)를 입력해주세요.');
+    }
+    try {
+        const result = await searchSevenElevenProducts({
+            query,
+            page,
+            size,
+            sort,
+        });
+        return successResponse(c, {
+            query: result.query,
+            count: result.products.length,
+            totalCount: result.totalCount,
+            collectionIds: result.collectionIds,
+            products: result.products,
+        }, {
+            total: result.totalCount,
+            page,
+            pageSize: size,
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : '알 수 없는 오류가 발생했습니다.';
+        return errorResponse(c, 'SEVENELEVEN_PRODUCT_SEARCH_FAILED', message, 500);
+    }
+}
+/**
+ * 세븐일레븐 매장 검색 API 핸들러
+ * GET /api/seveneleven/stores?keyword={검색어}&limit={개수}
+ */
+export async function handleSevenElevenSearchStores(c) {
+    const keyword = c.req.query('keyword') || '';
+    const limit = parseInt(c.req.query('limit') || '20', 10);
+    const safeLimit = Number.isFinite(limit) && limit > 0 ? limit : 20;
+    if (keyword.trim().length === 0) {
+        return errorResponse(c, 'MISSING_KEYWORD', '매장 검색어(keyword)를 입력해주세요.');
+    }
+    try {
+        const result = await fetchSevenElevenStoresByKeyword({
+            keyword,
+            limit: safeLimit,
+        });
+        return successResponse(c, {
+            keyword: result.query,
+            count: result.stores.length,
+            totalCount: result.totalCount,
+            stores: result.stores,
+        }, {
+            total: result.totalCount,
+            page: 1,
+            pageSize: safeLimit,
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : '알 수 없는 오류가 발생했습니다.';
+        return errorResponse(c, 'SEVENELEVEN_STORE_SEARCH_FAILED', message, 500);
+    }
+}
+/**
+ * 세븐일레븐 재고 확인 API 핸들러
+ * GET /api/seveneleven/inventory?keyword={검색어}&storeKeyword={매장키워드}
+ */
+export async function handleSevenElevenCheckInventory(c) {
+    const keyword = c.req.query('keyword') || '';
+    const storeKeyword = c.req.query('storeKeyword') || '';
+    const storeLimit = parseInt(c.req.query('storeLimit') || '20', 10);
+    const timeoutMs = parseInt(c.req.query('timeoutMs') || '20000', 10);
+    const safeStoreLimit = Number.isFinite(storeLimit) && storeLimit > 0 ? storeLimit : 20;
+    const safeTimeoutMs = Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : 20000;
+    if (keyword.trim().length === 0) {
+        return errorResponse(c, 'MISSING_QUERY', '검색어(keyword)를 입력해주세요.');
+    }
+    try {
+        const result = await checkSevenElevenInventory({
+            productKeyword: keyword,
+            storeKeyword,
+            storeLimit: safeStoreLimit,
+        }, {
+            timeout: safeTimeoutMs,
+        });
+        const note = result.stockAvailable
+            ? '실시간 재고 데이터가 포함되어 있습니다.'
+            : result.stockError
+                ? `실시간 재고 API 호출에 실패했습니다: ${result.stockError.message}`
+                : '실시간 재고 API가 현재 제한되어 있어 매장 목록만 제공됩니다.';
+        return successResponse(c, {
+            keyword,
+            storeKeyword,
+            product: result.product,
+            stockAvailable: result.stockAvailable,
+            stockError: result.stockError,
+            note,
+            inventory: {
+                totalStoreCount: result.totalStoreCount,
+                inStockStoreCount: result.inStockStoreCount,
+                count: result.stores.length,
+                stores: result.stores,
+            },
+        }, {
+            total: result.totalStoreCount,
+            pageSize: safeStoreLimit,
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : '알 수 없는 오류가 발생했습니다.';
+        return errorResponse(c, 'SEVENELEVEN_INVENTORY_CHECK_FAILED', message, 500);
+    }
+}
+/**
+ * 세븐일레븐 인기 검색어 API 핸들러
+ * GET /api/seveneleven/popwords?label={라벨}
+ */
+export async function handleSevenElevenGetSearchPopwords(c) {
+    const label = c.req.query('label') || 'home';
+    try {
+        const keywords = await fetchSevenElevenSearchPopwords(label);
+        return successResponse(c, {
+            label,
+            available: keywords.length > 0,
+            count: keywords.length,
+            keywords,
+            note: keywords.length === 0
+                ? '현재 응답에서 인기 검색어 목록을 찾지 못했습니다.'
+                : '홈 인기 검색어를 조회했습니다.',
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : '알 수 없는 오류가 발생했습니다.';
+        return errorResponse(c, 'SEVENELEVEN_POPWORD_FETCH_FAILED', message, 500);
+    }
+}
+/**
+ * 세븐일레븐 카탈로그 스냅샷 API 핸들러
+ * GET /api/seveneleven/catalog?includeIssues={bool}&includeExhibition={bool}&limit={개수}
+ */
+export async function handleSevenElevenGetCatalogSnapshot(c) {
+    const includeIssues = parseBoolean(c.req.query('includeIssues'), true);
+    const includeExhibition = parseBoolean(c.req.query('includeExhibition'), true);
+    const limit = parseInt(c.req.query('limit') || '20', 10);
+    try {
+        const result = await fetchSevenElevenCatalogSnapshot({
+            includeIssues,
+            includeExhibition,
+        });
+        return successResponse(c, {
+            options: {
+                includeIssues,
+                includeExhibition,
+                limit,
+            },
+            pages: {
+                totalCount: result.pages.length,
+                items: result.pages.slice(0, limit),
+            },
+            issues: {
+                totalCount: result.issues.length,
+                items: result.issues.slice(0, limit),
+            },
+            exhibitions: {
+                totalCount: result.exhibitions.length,
+                items: result.exhibitions.slice(0, limit),
+            },
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : '알 수 없는 오류가 발생했습니다.';
+        return errorResponse(c, 'SEVENELEVEN_CATALOG_FETCH_FAILED', message, 500);
+    }
+}
+/* c8 ignore stop */

package/dist/cli/args.js

@@ -0,0 +1,54 @@
+/**
+ * CLI 인자 파싱 및 URL 조작 유틸리티
+ */
+import { DEFAULT_BASE_URL } from './constants.js';
+export function parseCliArgs(args) {
+    const positionals = [];
+    const options = {};
+    for (let index = 0; index < args.length; index += 1) {
+        const token = args[index];
+        if (!token.startsWith('--')) {
+            positionals.push(token);
+            continue;
+        }
+        const withoutPrefix = token.slice(2);
+        const equalIndex = withoutPrefix.indexOf('=');
+        if (equalIndex >= 0) {
+            const key = withoutPrefix.slice(0, equalIndex);
+            const value = withoutPrefix.slice(equalIndex + 1);
+            options[key] = value;
+            continue;
+        }
+        const key = withoutPrefix;
+        const nextValue = args[index + 1];
+        if (!nextValue || nextValue.startsWith('--')) {
+            options[key] = 'true';
+            continue;
+        }
+        options[key] = nextValue;
+        index += 1;
+    }
+    return { positionals, options };
+}
+export function toUrl(pathOrUrl) {
+    if (pathOrUrl.startsWith('http://') || pathOrUrl.startsWith('https://')) {
+        return new URL(pathOrUrl);
+    }
+    const normalizedPath = pathOrUrl.startsWith('/') ? pathOrUrl : `/${pathOrUrl}`;
+    return new URL(normalizedPath, DEFAULT_BASE_URL);
+}
+export function applyOptionsToQuery(url, options) {
+    for (const [key, value] of Object.entries(options)) {
+        url.searchParams.set(key, value);
+    }
+}
+export function toQueryOptions(options) {
+    const queryOptions = {};
+    for (const [key, value] of Object.entries(options)) {
+        if (key === 'help' || key === 'json') {
+            continue;
+        }
+        queryOptions[key] = value;
+    }
+    return queryOptions;
+}