daiso 1.0.5 → 1.0.7

package/dist/services/gs25/client.js

@@ -2,15 +2,129 @@
  * GS25 API 클라이언트
  */
 /* c8 ignore start */
-import { fetchJson } from '../../utils/http.js';
+import { fetchJson, fetchWithTimeout, HttpError } from '../../utils/http.js';
+import { decodeZyteHttpBody, requestByZyte } from '../../utils/zyte.js';
 import { GS25_API } from './api.js';
 import { normalizeStore, toNumber } from './storeUtils.js';
 export { attachDistanceToGs25Stores, calculateDistanceM, extractGs25ProductCandidates, filterGs25StoresByKeyword, selectGs25StoresForKeyword, sortGs25Stores, } from './storeUtils.js';
 const GS25_DEFAULT_HEADERS = {
     Accept: 'application/json, text/plain, */*',
+    'Accept-Language': 'ko-KR,ko;q=0.9,en-US;q=0.8,en;q=0.7',
+    'User-Agent': 'Mozilla/5.0 (Linux; Android 15; SM-S928N) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/124.0 Mobile Safari/537.36',
+    Origin: 'https://woodongs.com',
+    Referer: 'https://woodongs.com/',
+};
+const GS25_TOTAL_SEARCH_HEADERS = {
+    ...GS25_DEFAULT_HEADERS,
+    'Content-Type': 'application/json',
+};
+const GS25_DEFAULT_FETCH_OPTIONS = {
+    retries: 1,
+    retryDelayMs: 250,
 };
 const GS25_STORES_CACHE_TTL_MS = 60 * 5 * 1000;
 const gs25StoresCache = new Map();
+function extractGs25WebCsrfToken(html) {
+    return (html.match(/name="CSRFToken"\s+value="([^"]+)"/)?.[1] ||
+        html.match(/ACC\.config\.CSRFToken\s*=\s*"([^"]+)"/)?.[1] ||
+        null);
+}
+function extractGs25WebCookieHeader(headers) {
+    const setCookie = headers.get('set-cookie') || '';
+    const jsessionId = setCookie.match(/JSESSIONID=[^;,\s]+/)?.[0];
+    return jsessionId;
+}
+function parseGs25WebLocationResponse(body) {
+    if (typeof body === 'string') {
+        return JSON.parse(body);
+    }
+    return body;
+}
+function normalizeGs25WebStore(raw) {
+    const propertyNames = (raw.offeringService || []).filter((item) => item.trim().length > 0);
+    return {
+        storeCode: raw.shopCode || '',
+        storeName: raw.shopName || '',
+        address: raw.address || '',
+        phone: '',
+        latitude: toNumber(raw.longs),
+        longitude: toNumber(raw.lat),
+        serviceCode: '01',
+        realStockQuantity: 0,
+        pickupStockQuantity: 0,
+        deliveryStockQuantity: 0,
+        isSoldOut: false,
+        searchItemName: '',
+        searchItemSellPrice: null,
+        propertyNames,
+        properties: propertyNames.map((name) => ({
+            code: name,
+            name,
+            type: 'service',
+            imageUrl: '',
+        })),
+        distanceM: null,
+    };
+}
+async function fetchGs25StoreStock(url, options) {
+    try {
+        return await fetchJson(url, {
+            ...GS25_DEFAULT_FETCH_OPTIONS,
+            method: 'GET',
+            timeout: options.timeout,
+            headers: GS25_DEFAULT_HEADERS,
+        });
+    }
+    catch (error) {
+        const zyteApiKey = options.zyteApiKey?.trim();
+        if (!(error instanceof HttpError) || error.status !== 403 || !zyteApiKey) {
+            throw error;
+        }
+        const result = await requestByZyte({
+            apiKey: zyteApiKey,
+            url,
+            method: 'GET',
+            timeout: options.timeout,
+            retries: 1,
+            headers: Object.entries(GS25_DEFAULT_HEADERS).map(([name, value]) => ({ name, value })),
+        });
+        return decodeZyteHttpBody(result);
+    }
+}
+async function fetchGs25TotalSearchResponse(query, options) {
+    const { timeout = 20000 } = options;
+    const endpoint = new URL(GS25_API.TOTAL_SEARCH_PATH, GS25_API.APIGW_BASE_URL);
+    const bodyText = JSON.stringify({ query });
+    try {
+        return await fetchJson(endpoint.toString(), {
+            ...GS25_DEFAULT_FETCH_OPTIONS,
+            method: 'POST',
+            retryUnsafeMethods: true,
+            timeout,
+            headers: GS25_TOTAL_SEARCH_HEADERS,
+            body: bodyText,
+        });
+    }
+    catch (error) {
+        const zyteApiKey = options.zyteApiKey?.trim();
+        if (!(error instanceof HttpError) || error.status !== 403 || !zyteApiKey) {
+            throw error;
+        }
+        const result = await requestByZyte({
+            apiKey: zyteApiKey,
+            url: endpoint.toString(),
+            method: 'POST',
+            timeout,
+            retries: 1,
+            headers: Object.entries(GS25_TOTAL_SEARCH_HEADERS).map(([name, value]) => ({
+                name,
+                value,
+            })),
+            bodyText,
+        });
+        return decodeZyteHttpBody(result);
+    }
+}
 function buildCacheKey(params) {
     return [
         params.serviceCode,
@@ -34,6 +148,7 @@ export async function geocodeGs25Address(address, options = {}) {
     endpoint.searchParams.set('address', keyword);
     endpoint.searchParams.set('key', apiKey);
     const body = await fetchJson(endpoint.toString(), {
+        ...GS25_DEFAULT_FETCH_OPTIONS,
         method: 'GET',
         timeout,
         headers: {
@@ -54,8 +169,94 @@ export async function geocodeGs25Address(address, options = {}) {
     }
     return { latitude, longitude };
 }
+export async function fetchGs25WebStores(keyword, options = {}) {
+    const query = keyword.trim();
+    if (query.length === 0) {
+        return { totalCount: 0, stores: [] };
+    }
+    const { timeout = 20000 } = options;
+    const locationsUrl = new URL(GS25_API.WEB_LOCATIONS_PATH, GS25_API.WEB_BASE_URL);
+    const locationsResponse = await fetchWithTimeout(locationsUrl.toString(), {
+        ...GS25_DEFAULT_FETCH_OPTIONS,
+        method: 'GET',
+        timeout,
+        headers: {
+            Accept: 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
+            'Accept-Language': GS25_DEFAULT_HEADERS['Accept-Language'],
+            'User-Agent': GS25_DEFAULT_HEADERS['User-Agent'],
+        },
+    });
+    if (!locationsResponse.ok) {
+        throw new HttpError(locationsResponse.status, locationsResponse.statusText, await locationsResponse.text());
+    }
+    const html = await locationsResponse.text();
+    const csrfToken = extractGs25WebCsrfToken(html);
+    if (!csrfToken) {
+        throw new Error('GS25 웹 매장 검색 CSRF 토큰을 찾을 수 없습니다.');
+    }
+    const form = new URLSearchParams({
+        pageNum: '1',
+        pageSize: '50',
+        searchShopName: query,
+        searchSido: '',
+        searchGugun: '',
+        searchDong: '',
+        searchType: '',
+        searchTypeService: '0',
+        searchTypeToto: '0',
+        searchTypeCafe25: '0',
+        searchTypeInstant: '0',
+        searchTypeDrug: '0',
+        searchTypeSelf25: '0',
+        searchTypePost: '0',
+        searchTypeATM: '0',
+        searchTypeWithdrawal: '0',
+        searchTypeTaxrefund: '0',
+        searchTypeSmartAtm: '0',
+        searchTypeSelfCookingUtensils: '0',
+        searchTypeDeliveryService: '0',
+        searchTypeParcelService: '0',
+        searchTypePotatoes: '0',
+        searchTypeCardiacDefi: '0',
+        searchTypeFishShapedBun: '0',
+        searchTypeWine25: '0',
+        searchTypeGoPizza: '0',
+        searchTypeSpiritWine: '0',
+        searchTypeFreshGanghw: '0',
+        searchTypeMusinsa: '0',
+        searchTypePosa: '0',
+    });
+    const locationListUrl = new URL(GS25_API.WEB_LOCATION_LIST_PATH, GS25_API.WEB_BASE_URL);
+    locationListUrl.searchParams.set('CSRFToken', csrfToken);
+    const cookieHeader = extractGs25WebCookieHeader(locationsResponse.headers);
+    const body = parseGs25WebLocationResponse(await fetchJson(locationListUrl.toString(), {
+        ...GS25_DEFAULT_FETCH_OPTIONS,
+        method: 'POST',
+        retryUnsafeMethods: true,
+        timeout,
+        headers: {
+            Accept: 'application/json, text/javascript, */*; q=0.01',
+            'Accept-Language': GS25_DEFAULT_HEADERS['Accept-Language'],
+            'Content-Type': 'application/x-www-form-urlencoded; charset=UTF-8',
+            Referer: locationsUrl.toString(),
+            'User-Agent': GS25_DEFAULT_HEADERS['User-Agent'],
+            'X-Requested-With': 'XMLHttpRequest',
+            ...(cookieHeader ? { Cookie: cookieHeader } : {}),
+        },
+        body: form.toString(),
+    }));
+    const stores = (body.results || [])
+        .map(normalizeGs25WebStore)
+        .filter((store) => store.storeCode.length > 0);
+    return {
+        totalCount: typeof body.pagination?.totalNumberOfResults === 'number'
+            ? body.pagination.totalNumberOfResults
+            : stores.length,
+        stores,
+    };
+}
 export async function fetchGs25Stores(params = {}, options = {}) {
-    const { serviceCode = '01', keyword = '', itemCode = '', storeCode = '', realTimeStockYn = 'Y', latitude, longitude, pageNumber = 0, pageCount = 20000, useCache = true, } = params;
+    const { serviceCode = '01', keyword = '', itemCode = '', storeCode = '', realTimeStockYn = 'Y', latitude, longitude, pageNumber, pageCount, useCache = true, } = params;
     const { timeout = 20000 } = options;
     const cacheKey = buildCacheKey({
         serviceCode,
@@ -77,9 +278,13 @@ export async function fetchGs25Stores(params = {}, options = {}) {
     }
     const endpoint = new URL(GS25_API.STORE_STOCK_PATH, GS25_API.BFF_BASE_URL);
     endpoint.searchParams.set('serviceCode', serviceCode);
-    endpoint.searchParams.set('pageNumber', String(pageNumber));
-    endpoint.searchParams.set('pageCount', String(pageCount));
     endpoint.searchParams.set('realTimeStockYn', realTimeStockYn);
+    if (typeof pageNumber === 'number' && Number.isFinite(pageNumber)) {
+        endpoint.searchParams.set('pageNumber', String(Math.trunc(pageNumber)));
+    }
+    if (typeof pageCount === 'number' && Number.isFinite(pageCount)) {
+        endpoint.searchParams.set('pageCount', String(Math.trunc(pageCount)));
+    }
     // itemCode가 있으면 itemCode 사용, 없으면 keyword 사용
     // 주의: itemCode 사용 시 좌표도 필수
     if (itemCode.trim().length > 0) {
@@ -108,12 +313,13 @@ export async function fetchGs25Stores(params = {}, options = {}) {
         endpoint.searchParams.set('isSuperDlvyStoreSelected', 'N');
         endpoint.searchParams.set('isGs25DlvyStoreSelected', 'N');
     }
-    const body = await fetchJson(endpoint.toString(), {
-        method: 'GET',
+    const body = await fetchGs25StoreStock(endpoint.toString(), {
         timeout,
-        headers: GS25_DEFAULT_HEADERS,
+        zyteApiKey: options.zyteApiKey,
     });
-    const stores = (body.stores || []).map(normalizeStore).filter((store) => store.storeCode.length > 0);
+    const stores = (body.stores || [])
+        .map(normalizeStore)
+        .filter((store) => store.storeCode.length > 0);
     if (useCache) {
         gs25StoresCache.set(cacheKey, {
             stores,
@@ -131,17 +337,7 @@ export async function fetchGs25NormalizedKeyword(keyword, options = {}) {
     if (query.length === 0) {
         return null;
     }
-    const { timeout = 20000 } = options;
-    const endpoint = new URL(GS25_API.TOTAL_SEARCH_PATH, GS25_API.APIGW_BASE_URL);
-    const body = await fetchJson(endpoint.toString(), {
-        method: 'POST',
-        timeout,
-        headers: {
-            Accept: 'application/json, text/plain, */*',
-            'Content-Type': 'application/json',
-        },
-        body: JSON.stringify({ query }),
-    });
+    const body = await fetchGs25TotalSearchResponse(query, options);
     const normalizedKeyword = body.SearchQueryResult?.keywordInfo?.keyword?.trim() || '';
     const normalizedSearchKeyword = body.SearchQueryResult?.keywordInfo?.searchKeyword?.trim() || '';
     if (normalizedKeyword.length === 0 && normalizedSearchKeyword.length === 0) {
@@ -161,17 +357,7 @@ export async function fetchGs25SearchProducts(keyword, options = {}) {
     if (query.length === 0) {
         return [];
     }
-    const { timeout = 20000 } = options;
-    const endpoint = new URL(GS25_API.TOTAL_SEARCH_PATH, GS25_API.APIGW_BASE_URL);
-    const body = await fetchJson(endpoint.toString(), {
-        method: 'POST',
-        timeout,
-        headers: {
-            Accept: 'application/json, text/plain, */*',
-            'Content-Type': 'application/json',
-        },
-        body: JSON.stringify({ query }),
-    });
+    const body = await fetchGs25TotalSearchResponse(query, options);
     const products = [];
     const collections = body.SearchQueryResult?.Collection || [];
     for (const collection of collections) {

package/dist/services/gs25/index.js

@@ -11,12 +11,20 @@ const GS25_METADATA = {
     description: 'GS25 매장 탐색, 상품 키워드 검색, 재고 조회 서비스',
 };
 class Gs25Service {
+    options;
     metadata = GS25_METADATA;
+    constructor(options = {}) {
+        this.options = options;
+    }
     getTools() {
-        return [createFindNearbyStoresTool(), createSearchProductsTool(), createCheckInventoryTool()];
+        return [
+            createFindNearbyStoresTool(this.options.googleMapsApiKey, this.options.zyteApiKey),
+            createSearchProductsTool(this.options.zyteApiKey),
+            createCheckInventoryTool(this.options.googleMapsApiKey, this.options.zyteApiKey),
+        ];
     }
 }
-export function createGs25Service() {
-    return new Gs25Service();
+export function createGs25Service(options = {}) {
+    return new Gs25Service(options);
 }
 export * from './types.js';

package/dist/services/gs25/tools/checkInventory.js

@@ -4,8 +4,11 @@
 /* c8 ignore start */
 import * as z from 'zod';
 import { attachDistanceToGs25Stores, fetchGs25SearchProducts, fetchGs25Stores, filterGs25StoresByKeyword, geocodeGs25Address, selectGs25StoresForKeyword, sortGs25Stores, } from '../client.js';
+function getProcessEnvValue(name) {
+    return typeof process !== 'undefined' ? process.env[name] : undefined;
+}
 async function checkInventory(args) {
-    const { keyword, itemCode: providedItemCode, latitude, longitude, storeKeyword = '', serviceCode = '01', storeLimit = 20, timeoutMs = 20000, } = args;
+    const { keyword, itemCode: providedItemCode, latitude, longitude, storeKeyword = '', serviceCode = '01', storeLimit = 20, timeoutMs = 20000, googleMapsApiKey = getProcessEnvValue('GOOGLE_MAPS_API_KEY'), zyteApiKey = getProcessEnvValue('ZYTE_API_KEY'), } = args;
     if (!keyword || keyword.trim().length === 0) {
         throw new Error('상품 검색어(keyword)를 입력해주세요.');
     }
@@ -21,13 +24,13 @@ async function checkInventory(args) {
             serviceCode,
         }, {
             timeout: timeoutMs,
+            zyteApiKey,
         });
-        const firstAddress = filterGs25StoresByKeyword(baseStores.stores, storeKeyword).find((store) => store.address.trim().length > 0)
-            ?.address || '';
+        const firstAddress = filterGs25StoresByKeyword(baseStores.stores, storeKeyword).find((store) => store.address.trim().length > 0)?.address || '';
         if (firstAddress.length > 0) {
             const geocoded = await geocodeGs25Address(firstAddress, {
                 timeout: timeoutMs,
-                googleMapsApiKey: process.env.GOOGLE_MAPS_API_KEY,
+                googleMapsApiKey,
             });
             if (geocoded) {
                 resolvedLatitude = geocoded.latitude;
@@ -57,11 +60,15 @@ async function checkInventory(args) {
             useCache: false,
         }, {
             timeout: timeoutMs,
+            zyteApiKey,
         });
     }
     else {
         // itemCode가 없으면 totalSearch API로 키워드 → itemCode 변환
-        const searchProducts = await fetchGs25SearchProducts(keyword, { timeout: timeoutMs });
+        const searchProducts = await fetchGs25SearchProducts(keyword, {
+            timeout: timeoutMs,
+            zyteApiKey,
+        });
         firstProduct = searchProducts.find((p) => p.itemCode.length > 0);
         if (firstProduct) {
             resolvedItemCode = firstProduct.itemCode;
@@ -75,6 +82,7 @@ async function checkInventory(args) {
                 useCache: false,
             }, {
                 timeout: timeoutMs,
+                zyteApiKey,
             });
         }
         else {
@@ -88,6 +96,7 @@ async function checkInventory(args) {
                 useCache: false,
             }, {
                 timeout: timeoutMs,
+                zyteApiKey,
             });
         }
     }
@@ -101,7 +110,8 @@ async function checkInventory(args) {
     const totalStockQuantity = filteredByStoreKeyword.reduce((sum, item) => sum + Math.max(item.realStockQuantity, 0), 0);
     // searchProducts에서 상품 정보 사용
     const firstProductName = firstProduct?.itemName || firstProduct?.shortItemName || null;
-    const firstProductPrice = filteredByStoreKeyword.find((item) => item.searchItemSellPrice !== null)?.searchItemSellPrice ?? null;
+    const firstProductPrice = filteredByStoreKeyword.find((item) => item.searchItemSellPrice !== null)?.searchItemSellPrice ??
+        null;
     return {
         content: [
             {
@@ -137,7 +147,7 @@ async function checkInventory(args) {
         ],
     };
 }
-export function createCheckInventoryTool() {
+export function createCheckInventoryTool(googleMapsApiKey, zyteApiKey) {
     return {
         name: 'gs25_check_inventory',
         metadata: {
@@ -149,15 +159,32 @@ export function createCheckInventoryTool() {
                     .string()
                     .optional()
                     .describe('상품 코드 (gs25_search_products로 조회한 정확한 코드, 제공 시 keyword 검색 건너뜀)'),
-                latitude: z.number().optional().describe('위도 (선택, 미입력 시 storeKeyword 지오코딩 시도)'),
-                longitude: z.number().optional().describe('경도 (선택, 미입력 시 storeKeyword 지오코딩 시도)'),
-                storeKeyword: z.string().optional().describe('매장명/주소 키워드 필터 (예: 강남, 안산 중앙역)'),
+                latitude: z
+                    .number()
+                    .optional()
+                    .describe('위도 (선택, 미입력 시 storeKeyword 지오코딩 시도)'),
+                longitude: z
+                    .number()
+                    .optional()
+                    .describe('경도 (선택, 미입력 시 storeKeyword 지오코딩 시도)'),
+                storeKeyword: z
+                    .string()
+                    .optional()
+                    .describe('매장명/주소 키워드 필터 (예: 강남, 안산 중앙역)'),
                 serviceCode: z.string().optional().default('01').describe('서비스 코드 (기본값: 01=GS25)'),
                 storeLimit: z.number().optional().default(20).describe('반환할 매장 수 (기본값: 20)'),
-                timeoutMs: z.number().optional().default(20000).describe('요청 제한 시간(ms, 기본값: 20000)'),
+                timeoutMs: z
+                    .number()
+                    .optional()
+                    .default(20000)
+                    .describe('요청 제한 시간(ms, 기본값: 20000)'),
             },
         },
-        handler: checkInventory,
+        handler: ((args) => checkInventory({
+            ...args,
+            googleMapsApiKey: args.googleMapsApiKey || googleMapsApiKey,
+            zyteApiKey: args.zyteApiKey || zyteApiKey,
+        })),
     };
 }
 /* c8 ignore stop */

package/dist/services/gs25/tools/findNearbyStores.js

@@ -4,8 +4,12 @@
 import * as z from 'zod';
 import { attachDistanceToGs25Stores, fetchGs25Stores, geocodeGs25Address, selectGs25StoresForKeyword, sortGs25Stores, } from '../client.js';
 const FALLBACK_STORE_LOOKUP_ITEM_CODE = '8801117752804';
+function getProcessEnvValue(name) {
+    /* c8 ignore next -- Node 테스트와 CLI 런타임은 process를 제공하며, Worker에는 API에서 키를 주입합니다. */
+    return typeof process !== 'undefined' ? process.env[name] : undefined;
+}
 async function findNearbyStores(args) {
-    const { latitude, longitude, keyword = '', serviceCode = '01', limit = 20, timeoutMs = 20000, } = args;
+    const { latitude, longitude, keyword = '', serviceCode = '01', limit = 20, timeoutMs = 20000, googleMapsApiKey = getProcessEnvValue('GOOGLE_MAPS_API_KEY'), zyteApiKey = getProcessEnvValue('ZYTE_API_KEY'), } = args;
     let resolvedLatitude = latitude;
     let resolvedLongitude = longitude;
     let geocodeUsed = false;
@@ -13,7 +17,7 @@ async function findNearbyStores(args) {
         keyword.trim().length > 0) {
         const geocoded = await geocodeGs25Address(keyword, {
             timeout: timeoutMs,
-            googleMapsApiKey: process.env.GOOGLE_MAPS_API_KEY,
+            googleMapsApiKey,
         });
         if (geocoded) {
             resolvedLatitude = geocoded.latitude;
@@ -27,6 +31,7 @@ async function findNearbyStores(args) {
         longitude: resolvedLongitude,
     }, {
         timeout: timeoutMs,
+        zyteApiKey,
     });
     let fallbackUsed = false;
     if (result.stores.length === 0 &&
@@ -42,6 +47,7 @@ async function findNearbyStores(args) {
                 useCache: false,
             }, {
                 timeout: timeoutMs,
+                zyteApiKey,
             });
             if (fallbackResult.stores.length > 0) {
                 result = fallbackResult;
@@ -83,7 +89,7 @@ async function findNearbyStores(args) {
         ],
     };
 }
-export function createFindNearbyStoresTool() {
+export function createFindNearbyStoresTool(googleMapsApiKey, zyteApiKey) {
     return {
         name: 'gs25_find_nearby_stores',
         metadata: {
@@ -95,9 +101,17 @@ export function createFindNearbyStoresTool() {
                 keyword: z.string().optional().describe('매장명/주소 키워드 (예: 강남, 안산 중앙역)'),
                 serviceCode: z.string().optional().default('01').describe('서비스 코드 (기본값: 01=GS25)'),
                 limit: z.number().optional().default(20).describe('반환할 최대 매장 수 (기본값: 20)'),
-                timeoutMs: z.number().optional().default(20000).describe('요청 제한 시간(ms, 기본값: 20000)'),
+                timeoutMs: z
+                    .number()
+                    .optional()
+                    .default(20000)
+                    .describe('요청 제한 시간(ms, 기본값: 20000)'),
             },
         },
-        handler: findNearbyStores,
+        handler: ((args) => findNearbyStores({
+            ...args,
+            googleMapsApiKey: args.googleMapsApiKey || googleMapsApiKey,
+            zyteApiKey: args.zyteApiKey || zyteApiKey,
+        })),
     };
 }

package/dist/services/gs25/tools/searchProducts.js

@@ -3,37 +3,50 @@
  */
 import * as z from 'zod';
 import { fetchGs25SearchProducts } from '../client.js';
+function getProcessEnvValue(name) {
+    if (typeof process !== 'undefined') {
+        return process.env[name];
+    }
+    /* c8 ignore next -- process가 없는 런타임 방어 분기 */
+    return undefined;
+}
+function buildTextResponse(payload) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+        structuredContent: payload,
+    };
+}
 async function searchProducts(args) {
-    const { keyword, limit = 20, timeoutMs = 20000 } = args;
+    const { keyword, limit = 20, timeoutMs = 20000, zyteApiKey = getProcessEnvValue('ZYTE_API_KEY'), } = args;
     if (!keyword || keyword.trim().length === 0) {
         throw new Error('상품 검색어(keyword)를 입력해주세요.');
     }
-    const products = await fetchGs25SearchProducts(keyword, { timeout: timeoutMs });
+    const products = await fetchGs25SearchProducts(keyword, { timeout: timeoutMs, zyteApiKey });
     const limitedProducts = products.slice(0, limit);
-    return {
-        content: [
-            {
-                type: 'text',
-                text: JSON.stringify({
-                    keyword,
-                    count: limitedProducts.length,
-                    products: limitedProducts.map((p) => ({
-                        itemCode: p.itemCode,
-                        itemName: p.itemName,
-                        shortItemName: p.shortItemName,
-                        imageUrl: p.imageUrl,
-                        rating: p.rating,
-                        stockCheckEnabled: p.stockCheckEnabled,
-                    })),
-                    note: limitedProducts.length === 0
-                        ? '검색 결과가 없습니다. 다른 키워드로 검색해보세요.'
-                        : '재고 확인 시 itemCode를 gs25_check_inventory에 전달하면 정확한 상품 재고를 조회할 수 있습니다.',
-                }, null, 2),
-            },
-        ],
+    const payload = {
+        keyword,
+        count: limitedProducts.length,
+        products: limitedProducts.map((p) => ({
+            itemCode: p.itemCode,
+            itemName: p.itemName,
+            shortItemName: p.shortItemName,
+            imageUrl: p.imageUrl,
+            rating: p.rating,
+            stockCheckEnabled: p.stockCheckEnabled,
+        })),
+        note: limitedProducts.length === 0
+            ? '검색 결과가 없습니다. 다른 키워드로 검색해보세요.'
+            : '재고 확인 시 itemCode를 gs25_check_inventory에 전달하면 정확한 상품 재고를 조회할 수 있습니다.',
     };
+    return buildTextResponse(payload);
 }
-export function createSearchProductsTool() {
+const searchProductsOutputSchema = {
+    keyword: z.string().describe('검색어'),
+    count: z.number().describe('반환된 상품 수'),
+    products: z.array(z.unknown()).describe('GS25 상품 검색 결과'),
+    note: z.string().describe('후속 재고 조회 안내'),
+};
+export function createSearchProductsTool(zyteApiKey) {
     return {
         name: 'gs25_search_products',
         metadata: {
@@ -44,7 +57,8 @@ export function createSearchProductsTool() {
                 limit: z.number().optional().default(20).describe('반환할 최대 상품 수 (기본값: 20)'),
                 timeoutMs: z.number().optional().default(20000).describe('요청 제한 시간(ms, 기본값: 20000)'),
             },
+            outputSchema: searchProductsOutputSchema,
         },
-        handler: searchProducts,
+        handler: ((args) => searchProducts({ ...args, zyteApiKey: zyteApiKey ?? args.zyteApiKey })),
     };
 }

package/dist/services/lottemart/client.js

@@ -7,7 +7,7 @@ import { __testOnlyClearLotteMartGeocodeCache, geocodeLotteMartAddress } from '.
 import { __testOnlyClearLotteMartSessionCache, fetchLotteMartHtml, fetchLotteMartPageWithSession, getCachedLotteMartSessionCookie, } from './session.js';
 import { attachDistance, fetchAllStoresForAreaList, fetchKeywordMatchedStores, getTargetAreas, normalizeArea, toDisplayArea, } from './storeSearch.js';
 import { calculateDistanceM, dedupeProducts, matchesBrandVariant, matchesKeyword, parseMarketOptions, parseProductSummary, parseProducts, parseStores, sortStores, } from './parser.js';
-import { createZettaFallbackStore, fetchZettaLotteMartProductsWithPrimaryError } from './zetta.js';
+import { createZettaFallbackStore, fetchZettaLotteMartProducts, fetchZettaLotteMartProductsWithPrimaryError } from './zetta.js';
 const STORE_CACHE_TTL_MS = 30 * 60 * 1000;
 const LOTTEMART_PRODUCT_LEGACY_TIMEOUT_MS = 7000;
 const storeCache = new Map();
@@ -177,6 +177,9 @@ export async function searchLotteMartProducts(params, options = {}) {
         throw new Error('상품 검색어(keyword)를 입력해주세요.');
     }
     const timeout = options.timeout || DEFAULT_LOTTEMART_TIMEOUT_MS;
+    if (params.source === 'zetta') {
+        return fetchZettaLotteMartProducts(createZettaFallbackStore(params), normalizedKeyword, params.pageLimit || 3, timeout);
+    }
     const sessionCookie = await getLotteMartSessionCookie({ timeout: LOTTEMART_PRODUCT_LEGACY_TIMEOUT_MS });
     let resolvedStore;
     try {
@@ -187,6 +190,9 @@ export async function searchLotteMartProducts(params, options = {}) {
         });
     }
     catch (error) {
+        if (params.source === 'legacy') {
+            throw error;
+        }
         const fallbackStore = createZettaFallbackStore(params);
         return fetchZettaLotteMartProductsWithPrimaryError(fallbackStore, normalizedKeyword, params.pageLimit || 3, timeout, error);
     }
@@ -208,6 +214,9 @@ export async function searchLotteMartProducts(params, options = {}) {
         }, LOTTEMART_PRODUCT_LEGACY_TIMEOUT_MS, sessionCookie, options.zyteApiKey);
     }
     catch (error) {
+        if (params.source === 'legacy') {
+            throw error;
+        }
         return fetchZettaLotteMartProductsWithPrimaryError(resolvedStore, normalizedKeyword, params.pageLimit || 3, timeout, error);
     }
     const pagedSessionCookie = await getCachedLotteMartSessionCookie(LOTTEMART_PRODUCT_LEGACY_TIMEOUT_MS);

package/dist/services/lottemart/tools/searchProducts.js

@@ -5,13 +5,14 @@ import * as z from 'zod';
 import { searchLotteMartProducts } from '../client.js';
 import { DEFAULT_LOTTEMART_TIMEOUT_MS } from '../config.js';
 async function searchProducts(args) {
-    const { area, storeCode, storeName, keyword, pageLimit = 3, timeoutMs = DEFAULT_LOTTEMART_TIMEOUT_MS, zyteApiKey, } = args;
+    const { area, storeCode, storeName, keyword, pageLimit = 3, source = 'auto', timeoutMs = DEFAULT_LOTTEMART_TIMEOUT_MS, zyteApiKey, } = args;
     const result = await searchLotteMartProducts({
         area,
         storeCode,
         storeName,
         keyword,
         pageLimit,
+        source,
     }, {
         timeout: timeoutMs,
         zyteApiKey,
@@ -26,6 +27,7 @@ async function searchProducts(args) {
                     storeName: result.storeName,
                     keyword,
                     pageLimit,
+                    source,
                     totalCount: result.totalCount,
                     totalPages: result.totalPages,
                     count: result.products.length,
@@ -47,6 +49,11 @@ export function createSearchProductsTool(zyteApiKey) {
                 storeName: z.string().optional().describe('매장명 (예: 강변점)'),
                 keyword: z.string().describe('상품 검색어 (예: 콜라, 우유, 과자)'),
                 pageLimit: z.number().optional().default(3).describe('추가 조회할 최대 페이지 수 (기본값: 3)'),
+                source: z
+                    .enum(['auto', 'legacy', 'zetta'])
+                    .optional()
+                    .default('auto')
+                    .describe('상품 검색 경로 (auto: 구형 경로 후 제타 대체, zetta: 빠른 제타 API 우선, legacy: 구형 경로만 사용)'),
                 timeoutMs: z
                     .number()
                     .optional()