daiso 1.0.5 → 1.0.6

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()

package/dist/services/lottemart/zetta.js

@@ -71,7 +71,7 @@ function clampZettaPageLimit(pageLimit) {
     }
     return pageLimit;
 }
-async function fetchZettaLotteMartProducts(resolvedStore, keyword, pageLimit, timeout) {
+export async function fetchZettaLotteMartProducts(resolvedStore, keyword, pageLimit, timeout) {
     const products = [];
     let nextPageToken;
     let fetchedPages = 0;

package/dist/services/oliveyoung/client.js

@@ -6,6 +6,10 @@
 import { OLIVEYOUNG_API } from './api.js';
 import { decodeBase64, requestByZyte } from '../../utils/zyte.js';
 const OLIVEYOUNG_IMAGE_HOST = 'https://image.oliveyoung.co.kr';
+const OLIVEYOUNG_PRODUCT_ID_CACHE_TTL_MS = 10 * 60 * 1000;
+const OLIVEYOUNG_PRODUCT_SEARCH_STALE_CACHE_TTL_MS = 30 * 60 * 1000;
+const oliveyoungProductIdCache = new Map();
+const oliveyoungProductSearchCache = new Map();
 const OLIVEYOUNG_IMAGE_PATH_PREFIX = '/uploads/images/goods';
 function resolveOliveyoungInStock(o2oStockFlag, o2oRemainQuantity) {
     return o2oStockFlag || o2oRemainQuantity > 0;
@@ -60,6 +64,29 @@ function resolveOliveyoungStoreStock(rawStore) {
         openYn: Boolean(rawStore?.openYn),
     };
 }
+function createOliveyoungProductSearchCacheKey(params) {
+    return JSON.stringify([params.keyword, params.page, params.size, params.sort, params.includeSoldOut]);
+}
+function cloneOliveyoungProductSearchResult(result) {
+    return {
+        totalCount: result.totalCount,
+        nextPage: result.nextPage,
+        products: result.products.map((product) => ({ ...product })),
+    };
+}
+function readStaleOliveyoungProductSearchResult(cacheKey) {
+    const cached = oliveyoungProductSearchCache.get(cacheKey);
+    if (!cached || cached.expiresAt <= Date.now()) {
+        return null;
+    }
+    return cloneOliveyoungProductSearchResult(cached.result);
+}
+function writeStaleOliveyoungProductSearchResult(cacheKey, result) {
+    oliveyoungProductSearchCache.set(cacheKey, {
+        expiresAt: Date.now() + OLIVEYOUNG_PRODUCT_SEARCH_STALE_CACHE_TTL_MS,
+        result: cloneOliveyoungProductSearchResult(result),
+    });
+}
 async function zyteExtract(targetPath, requestBody, options = {}) {
     const { timeout = 15000, apiKey } = options;
     try {
@@ -126,37 +153,65 @@ export async function fetchOliveyoungProducts(params, options = {}) {
         sort: params.sort,
         size: params.size,
     };
-    const body = await zyteExtract(OLIVEYOUNG_API.PRODUCT_SEARCH_PATH, payload, options);
-    const list = body.data?.serachList || body.data?.searchList || [];
-    const products = list.map((product) => {
-        const o2oStockFlag = Boolean(product.o2oStockFlag);
-        const o2oRemainQuantity = product.o2oRemainQuantity || 0;
-        const inStock = resolveOliveyoungInStock(o2oStockFlag, o2oRemainQuantity);
-        const stockStatus = inStock ? 'in_stock' : 'out_of_stock';
-        const stockSource = 'global_search';
-        return {
-            goodsNumber: product.goodsNumber || '',
-            goodsName: product.goodsName || '',
-            imageUrl: resolveOliveyoungImageUrl(product.imagePath),
-            priceToPay: product.priceToPay || 0,
-            originalPrice: product.originalPrice || 0,
-            discountRate: product.discountRate || 0,
-            o2oStockFlag,
-            o2oRemainQuantity,
-            inStock,
-            stockStatus,
-            stockSource,
+    const cacheKey = createOliveyoungProductSearchCacheKey(params);
+    try {
+        const body = await zyteExtract(OLIVEYOUNG_API.PRODUCT_SEARCH_PATH, payload, options);
+        const list = body.data?.serachList || body.data?.searchList || [];
+        const products = list.map((product) => {
+            const o2oStockFlag = Boolean(product.o2oStockFlag);
+            const o2oRemainQuantity = product.o2oRemainQuantity || 0;
+            const inStock = resolveOliveyoungInStock(o2oStockFlag, o2oRemainQuantity);
+            const stockStatus = inStock ? 'in_stock' : 'out_of_stock';
+            const stockSource = 'global_search';
+            return {
+                goodsNumber: product.goodsNumber || '',
+                goodsName: product.goodsName || '',
+                imageUrl: resolveOliveyoungImageUrl(product.imagePath),
+                priceToPay: product.priceToPay || 0,
+                originalPrice: product.originalPrice || 0,
+                discountRate: product.discountRate || 0,
+                o2oStockFlag,
+                o2oRemainQuantity,
+                inStock,
+                stockStatus,
+                stockSource,
+            };
+        });
+        const result = {
+            totalCount: body.data?.totalCount || 0,
+            nextPage: Boolean(body.data?.nextPage),
+            products,
         };
-    });
-    return {
-        totalCount: body.data?.totalCount || 0,
-        nextPage: Boolean(body.data?.nextPage),
-        products,
-    };
+        writeStaleOliveyoungProductSearchResult(cacheKey, result);
+        return result;
+    }
+    catch (error) {
+        const staleResult = readStaleOliveyoungProductSearchResult(cacheKey);
+        if (staleResult) {
+            return staleResult;
+        }
+        throw error;
+    }
 }
 async function fetchOliveyoungProductId(goodsNumber, options = {}) {
-    const body = await zyteExtract(OLIVEYOUNG_API.STOCK_GOODS_INFO_PATH, { goodsNo: goodsNumber }, options);
-    return body.data?.goodsInfo?.masterGoodsNumber || '';
+    const normalizedGoodsNumber = goodsNumber.trim();
+    if (!normalizedGoodsNumber) {
+        return '';
+    }
+    const cached = oliveyoungProductIdCache.get(normalizedGoodsNumber);
+    const now = Date.now();
+    if (cached && cached.expiresAt > now) {
+        return cached.productId;
+    }
+    const body = await zyteExtract(OLIVEYOUNG_API.STOCK_GOODS_INFO_PATH, { goodsNo: normalizedGoodsNumber }, options);
+    const productId = body.data?.goodsInfo?.masterGoodsNumber || '';
+    if (productId) {
+        oliveyoungProductIdCache.set(normalizedGoodsNumber, {
+            expiresAt: now + OLIVEYOUNG_PRODUCT_ID_CACHE_TTL_MS,
+            productId,
+        });
+    }
+    return productId;
 }
 async function fetchOliveyoungStockStores(params, options = {}) {
     const body = await zyteExtract(OLIVEYOUNG_API.STOCK_STORES_PATH, {
@@ -193,39 +248,55 @@ export async function enrichOliveyoungProductsWithNearbyStoreInventory(products,
     if (maxProducts === 0) {
         return { checkedCount: 0, products };
     }
-    const enrichedProducts = [];
-    let checkedCount = 0;
-    for (const [index, product] of products.entries()) {
-        if (index >= maxProducts) {
-            enrichedProducts.push(product);
-            continue;
+    const checkedProducts = await Promise.all(products.slice(0, maxProducts).map(async (product) => {
+        let productId = '';
+        try {
+            productId = await fetchOliveyoungProductId(product.goodsNumber, options);
+        }
+        catch {
+            return { checked: false, product };
         }
-        const productId = await fetchOliveyoungProductId(product.goodsNumber, options);
         if (!productId) {
-            enrichedProducts.push(product);
-            continue;
+            return { checked: false, product };
+        }
+        let storeInventory;
+        try {
+            storeInventory = await fetchOliveyoungStockStores({
+                productId,
+                latitude: params.latitude,
+                longitude: params.longitude,
+                pageIdx: 1,
+                searchWords: params.storeKeyword,
+            }, options);
+        }
+        catch {
+            return { checked: false, product };
         }
-        const storeInventory = await fetchOliveyoungStockStores({
-            productId,
-            latitude: params.latitude,
-            longitude: params.longitude,
-            pageIdx: 1,
-            searchWords: params.storeKeyword,
-        }, options);
-        checkedCount += 1;
         const inStock = storeInventory.inStockCount > 0;
         const stockStatus = inStock ? 'in_stock' : 'out_of_stock';
         const stockSource = 'nearby_store';
-        enrichedProducts.push({
-            ...product,
-            inStock,
-            stockStatus,
-            stockSource,
-            storeInventory,
-        });
-    }
+        return {
+            checked: true,
+            product: {
+                ...product,
+                inStock,
+                stockStatus,
+                stockSource,
+                storeInventory,
+            },
+        };
+    }));
+    const enrichedProducts = [
+        ...checkedProducts.map((result) => result.product),
+        ...products.slice(maxProducts),
+    ];
+    const checkedCount = checkedProducts.filter((result) => result.checked).length;
     return {
         checkedCount,
         products: sortOliveyoungProducts(enrichedProducts),
     };
 }
+export function __testOnlyClearOliveyoungCaches() {
+    oliveyoungProductIdCache.clear();
+    oliveyoungProductSearchCache.clear();
+}

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

@@ -4,7 +4,7 @@
 import * as z from 'zod';
 import { enrichOliveyoungProductsWithNearbyStoreInventory, fetchOliveyoungProducts, fetchOliveyoungStores, } from '../client.js';
 async function checkInventory(args) {
-    const { keyword, latitude = 37.5665, longitude = 126.978, storeKeyword = '', page = 1, size = 20, sort = '01', includeSoldOut = false, storeLimit = 10, timeoutMs = 15000, zyteApiKey, } = args;
+    const { keyword, latitude = 37.5665, longitude = 126.978, storeKeyword = '', page = 1, size = 20, sort = '01', includeSoldOut = false, storeLimit = 10, stockCheckLimit = 5, timeoutMs = 15000, zyteApiKey, } = args;
     if (!keyword || keyword.trim().length === 0) {
         throw new Error('상품 검색어(keyword)를 입력해주세요.');
     }
@@ -33,7 +33,7 @@ async function checkInventory(args) {
         latitude,
         longitude,
         storeKeyword,
-        maxProducts: Math.min(productResult.products.length, 5),
+        maxProducts: Math.min(productResult.products.length, Math.max(0, stockCheckLimit)),
     }, {
         timeout: timeoutMs,
         apiKey: zyteApiKey,
@@ -90,6 +90,11 @@ export function createCheckInventoryTool(apiKey) {
                 sort: z.string().optional().default('01').describe('정렬 코드 (기본값: 01)'),
                 includeSoldOut: z.boolean().optional().default(false).describe('품절 상품 포함 여부 (기본값: false)'),
                 storeLimit: z.number().optional().default(10).describe('반환할 주변 매장 최대 수 (기본값: 10)'),
+                stockCheckLimit: z
+                    .number()
+                    .optional()
+                    .default(5)
+                    .describe('주변 매장별 재고를 보강할 상품 수 (기본값: 5, 낮출수록 빠름)'),
                 timeoutMs: z.number().optional().default(15000).describe('요청 제한 시간(ms, 기본값: 15000)'),
             },
         },

package/dist/services/seveneleven/client.js

@@ -9,6 +9,10 @@ const SEVENELEVEN_DEFAULT_HEADERS = {
     'Content-Type': 'application/json',
     'User-Agent': 'Mozilla/5.0 (Linux; Android 15)',
 };
+const SEVENELEVEN_DEFAULT_FETCH_OPTIONS = {
+    retries: 1,
+    retryDelayMs: 250,
+};
 function toNumber(value) {
     if (typeof value === 'number') {
         return Number.isFinite(value) ? value : 0;
@@ -108,7 +112,9 @@ async function requestSevenElevenJson(path, method, body, options = {}) {
     const { timeout = 15000 } = options;
     const url = `${SEVENELEVEN_API.BASE_URL}${path}`;
     return fetchJson(url, {
+        ...SEVENELEVEN_DEFAULT_FETCH_OPTIONS,
         method,
+        retryUnsafeMethods: method === 'POST',
         timeout,
         headers: SEVENELEVEN_DEFAULT_HEADERS,
         body: method === 'POST' ? JSON.stringify(body || {}) : undefined,
@@ -211,6 +217,7 @@ export async function fetchSevenElevenStockProductMeta(itemCode, options = {}) {
     const encodedItemCode = encodeURIComponent(itemCode.trim());
     const url = `${SEVENELEVEN_API.BASE_URL}${SEVENELEVEN_API.PRODUCT_SEARCH_STOCK_PATH}?itemCd=${encodedItemCode}`;
     const response = await fetchJson(url, {
+        ...SEVENELEVEN_DEFAULT_FETCH_OPTIONS,
         method: 'GET',
         timeout,
         headers: {

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

@@ -3,6 +3,12 @@
  */
 import * as z from 'zod';
 import { searchSevenElevenProductsWithVariants } from '../productKeyword.js';
+function buildTextResponse(payload) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+        structuredContent: payload,
+    };
+}
 async function searchProducts(args) {
     const { query, page = 1, size = 20, sort = 'recommend', timeoutMs = 15000 } = args;
     if (!query || query.trim().length === 0) {
@@ -14,25 +20,29 @@ async function searchProducts(args) {
         sort,
         timeout: timeoutMs,
     });
-    return {
-        content: [
-            {
-                type: 'text',
-                text: JSON.stringify({
-                    query: result.query,
-                    page,
-                    size,
-                    sort,
-                    totalCount: result.totalCount,
-                    count: result.products.length,
-                    collectionIds: result.collectionIds,
-                    appliedQueries: result.appliedQueries,
-                    products: result.products,
-                }, null, 2),
-            },
-        ],
-    };
+    return buildTextResponse({
+        query: result.query,
+        page,
+        size,
+        sort,
+        totalCount: result.totalCount,
+        count: result.products.length,
+        collectionIds: result.collectionIds,
+        appliedQueries: result.appliedQueries,
+        products: result.products,
+    });
 }
+const searchProductsOutputSchema = {
+    query: z.string().describe('적용된 검색어'),
+    page: z.number().describe('페이지 번호'),
+    size: z.number().describe('페이지 크기'),
+    sort: z.string().describe('정렬 기준'),
+    totalCount: z.number().describe('검색된 전체 상품 수'),
+    count: z.number().describe('반환된 상품 수'),
+    collectionIds: z.array(z.string()).describe('검색 컬렉션 ID 목록'),
+    appliedQueries: z.array(z.string()).describe('실제로 시도한 검색어 목록'),
+    products: z.array(z.unknown()).describe('세븐일레븐 상품 검색 결과'),
+};
 export function createSearchProductsTool() {
     return {
         name: 'seveneleven_search_products',
@@ -50,6 +60,7 @@ export function createSearchProductsTool() {
                     .describe('정렬 기준 (기본값: recommend)'),
                 timeoutMs: z.number().optional().default(15000).describe('요청 제한 시간(ms, 기본값: 15000)'),
             },
+            outputSchema: searchProductsOutputSchema,
         },
         handler: searchProducts,
     };

package/dist/utils/http.js

@@ -20,18 +20,90 @@ export function createTimeoutController(timeout) {
     const timeoutId = setTimeout(() => controller.abort(), timeout);
     return { controller, timeoutId };
 }
-export async function fetchWithTimeout(url, options = {}) {
-    const { timeout = 10000, ...restOptions } = options;
-    const { controller, timeoutId } = createTimeoutController(timeout);
-    try {
-        return await fetch(url, {
-            ...restOptions,
-            signal: controller.signal,
-        });
+const DEFAULT_RETRY_STATUS_CODES = [408, 429, 500, 502, 503, 504, 522, 524];
+const DEFAULT_RETRY_METHODS = ['GET', 'HEAD', 'OPTIONS'];
+function isRetryableStatus(status, retryStatusCodes) {
+    return retryStatusCodes.includes(status);
+}
+function wait(ms) {
+    if (ms <= 0) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+function normalizeMethod(method) {
+    return (method || 'GET').toUpperCase();
+}
+function canRetryMethod(method, retryMethods, retryUnsafeMethods) {
+    return retryUnsafeMethods || retryMethods.map((item) => item.toUpperCase()).includes(method);
+}
+function parseRetryAfterDelayMs(response) {
+    const retryAfter = response.headers.get('retry-after');
+    if (!retryAfter) {
+        return null;
+    }
+    const seconds = Number.parseFloat(retryAfter);
+    if (Number.isFinite(seconds)) {
+        return Math.max(0, Math.trunc(seconds * 1000));
+    }
+    const retryDate = Date.parse(retryAfter);
+    if (Number.isFinite(retryDate)) {
+        return Math.max(0, retryDate - Date.now());
     }
-    finally {
-        clearTimeout(timeoutId);
+    return null;
+}
+export async function fetchWithTimeout(url, options = {}) {
+    const { timeout = 10000, retries = 0, retryDelayMs = 250, retryStatusCodes = DEFAULT_RETRY_STATUS_CODES, retryUnsafeMethods = false, retryMethods = DEFAULT_RETRY_METHODS, onRetry, ...restOptions } = options;
+    const maxAttempts = Math.max(1, Math.trunc(retries) + 1);
+    const method = normalizeMethod(restOptions.method);
+    const retryAllowed = canRetryMethod(method, retryMethods, retryUnsafeMethods);
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        const { controller, timeoutId } = createTimeoutController(timeout);
+        try {
+            const response = await fetch(url, {
+                ...restOptions,
+                signal: controller.signal,
+            });
+            if (retryAllowed && attempt < maxAttempts && isRetryableStatus(response.status, retryStatusCodes)) {
+                const delayMs = parseRetryAfterDelayMs(response) ?? retryDelayMs;
+                onRetry?.({
+                    attempt,
+                    maxAttempts,
+                    delayMs,
+                    reason: 'status',
+                    status: response.status,
+                    method,
+                    url,
+                });
+                await response.body?.cancel();
+                await wait(delayMs);
+                continue;
+            }
+            return response;
+        }
+        catch (error) {
+            if (!retryAllowed || attempt >= maxAttempts) {
+                throw error;
+            }
+            onRetry?.({
+                attempt,
+                maxAttempts,
+                delayMs: retryDelayMs,
+                reason: 'error',
+                error,
+                method,
+                url,
+            });
+            await wait(retryDelayMs);
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
     }
+    /* v8 ignore next */
+    throw new Error('API 요청 재시도 처리 중 알 수 없는 오류가 발생했습니다.');
 }
 export async function fetchJson(url, options = {}) {
     const response = await fetchWithTimeout(url, options);

package/dist/utils/zyte.js

@@ -37,36 +37,57 @@ export function decodeBase64(value) {
     /* c8 ignore end */
     throw new Error('Base64 디코딩을 지원하지 않는 런타임입니다.');
 }
+function isAbortError(error) {
+    return error instanceof Error && error.name === 'AbortError';
+}
+function wait(ms) {
+    if (ms <= 0) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
 export async function requestByZyte(options) {
-    const { timeout = 15000, url, method = 'GET', headers = [], bodyText, apiKey } = options;
+    const { timeout = 15000, retries = 1, retryDelayMs = 250, url, method = 'GET', headers = [], bodyText, apiKey, } = options;
     const auth = encodeBasicAuth(resolveZyteApiKey(apiKey));
-    const { controller, timeoutId } = createTimeoutController(timeout);
-    try {
-        const response = await fetch('https://api.zyte.com/v1/extract', {
-            method: 'POST',
-            headers: {
-                Authorization: `Basic ${auth}`,
-                'Content-Type': 'application/json',
-                Accept: 'application/json',
-            },
-            body: JSON.stringify({
-                url,
-                httpRequestMethod: method,
-                customHttpRequestHeaders: headers,
-                httpRequestText: bodyText,
-                httpResponseBody: true,
-            }),
-            signal: controller.signal,
-        });
-        const result = (await response.json());
-        if (!response.ok) {
-            throw new Error(`Zyte API 호출 실패: ${response.status} ${result.detail || result.title || ''}`.trim());
+    const maxAttempts = Math.max(1, Math.trunc(retries) + 1);
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        const { controller, timeoutId } = createTimeoutController(timeout);
+        try {
+            const response = await fetch('https://api.zyte.com/v1/extract', {
+                method: 'POST',
+                headers: {
+                    Authorization: `Basic ${auth}`,
+                    'Content-Type': 'application/json',
+                    Accept: 'application/json',
+                },
+                body: JSON.stringify({
+                    url,
+                    httpRequestMethod: method,
+                    customHttpRequestHeaders: headers,
+                    httpRequestText: bodyText,
+                    httpResponseBody: true,
+                }),
+                signal: controller.signal,
+            });
+            const result = (await response.json());
+            if (!response.ok) {
+                throw new Error(`Zyte API 호출 실패: ${response.status} ${result.detail || result.title || ''}`.trim());
+            }
+            return result;
+        }
+        catch (error) {
+            if (!isAbortError(error) || attempt >= maxAttempts) {
+                throw error;
+            }
+            await wait(retryDelayMs);
+        }
+        finally {
+            clearTimeout(timeoutId);
         }
-        return result;
-    }
-    finally {
-        clearTimeout(timeoutId);
     }
+    throw new Error('Zyte API 호출 실패');
 }
 export function decodeZyteHttpBody(result) {
     if (!result.httpResponseBody) {

package/openapi.json

@@ -96,7 +96,7 @@
             "name": "productId",
             "in": "query",
             "required": false,
-            "description": "제품 ID 또는 상세 조회용 path 파라미터",
+            "description": "제품 ID 또는 상세 조회용 path 파라미터. 상품명만 알면 먼저 daisoSearchProducts 또는 /api/daiso/products로 productId를 확인하세요.",
             "schema": {
               "type": "string"
             }
@@ -278,7 +278,7 @@
             "name": "storeCode",
             "in": "query",
             "required": false,
-            "description": "매장 코드",
+            "description": "매장 코드. 다이소 진열 위치는 /api/daiso/inventory 응답의 storeInventory.stores[].storeCode에서 확인하세요.",
             "schema": {
               "type": "string"
             }
@@ -287,7 +287,7 @@
             "name": "storeName",
             "in": "query",
             "required": false,
-            "description": "매장명",
+            "description": "매장명. 롯데마트 상품 조회에서 storeCode가 없을 때 사용하며, 모르면 먼저 lottemartFindNearbyStores 또는 /api/lottemart/stores로 확인하세요.",
             "schema": {
               "type": "string"
             }