daiso 1.0.4 → 1.0.5

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

@@ -0,0 +1,57 @@
+/**
+ * 올리브영 상품 검색 도구
+ */
+import * as z from 'zod';
+import { fetchOliveyoungProducts } from '../client.js';
+async function searchProducts(args) {
+    const { keyword, page = 1, size = 20, sort = '01', includeSoldOut = false, timeoutMs = 15000, zyteApiKey, } = args;
+    if (!keyword || keyword.trim().length === 0) {
+        throw new Error('상품 검색어(keyword)를 입력해주세요.');
+    }
+    const result = await fetchOliveyoungProducts({
+        keyword,
+        page,
+        size,
+        sort,
+        includeSoldOut,
+    }, {
+        timeout: timeoutMs,
+        apiKey: zyteApiKey,
+    });
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({
+                    keyword,
+                    page,
+                    size,
+                    sort,
+                    includeSoldOut,
+                    totalCount: result.totalCount,
+                    nextPage: result.nextPage,
+                    count: result.products.length,
+                    products: result.products,
+                }, null, 2),
+            },
+        ],
+    };
+}
+export function createSearchProductsTool(apiKey) {
+    return {
+        name: 'oliveyoung_search_products',
+        metadata: {
+            title: '올리브영 상품 검색',
+            description: '키워드로 올리브영 상품 목록을 조회합니다. "어떤 거 있나요" 같은 질문에는 먼저 이 도구를 사용하세요.',
+            inputSchema: {
+                keyword: z.string().describe('상품 검색어 (예: 마스크팩, 선크림, 립밤)'),
+                page: z.number().optional().default(1).describe('상품 검색 페이지 번호 (기본값: 1)'),
+                size: z.number().optional().default(20).describe('페이지당 상품 수 (기본값: 20)'),
+                sort: z.string().optional().default('01').describe('정렬 코드 (기본값: 01)'),
+                includeSoldOut: z.boolean().optional().default(false).describe('품절 상품 포함 여부 (기본값: false)'),
+                timeoutMs: z.number().optional().default(15000).describe('요청 제한 시간(ms, 기본값: 15000)'),
+            },
+        },
+        handler: ((args) => searchProducts({ ...args, zyteApiKey: apiKey })),
+    };
+}

package/dist/services/seveneleven/api.js

@@ -0,0 +1,15 @@
+/**
+ * 세븐일레븐 API 엔드포인트
+ */
+export const SEVENELEVEN_API = {
+    BASE_URL: 'https://new.7-elevenapp.co.kr',
+    SEARCH_GOODS_PATH: '/api/v1/open/search/goods',
+    SEARCH_STORE_PATH: '/api/v1/open/search/store',
+    SEARCH_POPWORD_PATH: '/api/v1/open/search/popword',
+    PRODUCT_SEARCH_STOCK_PATH: '/api/v1/open/product/search/stock',
+    STOCK_SEARCH_STORES_PATH: '/api/v1/open/stock/search/stores',
+    REAL_STOCK_MULTI_PATH: '/api/v1/open/real-stock/multi',
+    PRODUCT_PAGES_PATH: '/api/v1/product/pages',
+    PRODUCT_ISSUES_PATH: '/api/v1/product/issues',
+    EXHIBITION_MAIN_PATH: '/api/v1/exhibition/main/list',
+};

package/dist/services/seveneleven/client.js

@@ -0,0 +1,279 @@
+/**
+ * 세븐일레븐 API 클라이언트
+ */
+/* c8 ignore start */
+import { fetchJson } from '../../utils/http.js';
+import { SEVENELEVEN_API } from './api.js';
+const SEVENELEVEN_DEFAULT_HEADERS = {
+    Accept: 'application/json, text/plain, */*',
+    'Content-Type': 'application/json',
+    'User-Agent': 'Mozilla/5.0 (Linux; Android 15)',
+};
+function toNumber(value) {
+    if (typeof value === 'number') {
+        return Number.isFinite(value) ? value : 0;
+    }
+    if (typeof value === 'string') {
+        const parsed = Number.parseFloat(value);
+        return Number.isFinite(parsed) ? parsed : 0;
+    }
+    return 0;
+}
+function toStringValue(value) {
+    return typeof value === 'string' ? value : '';
+}
+function normalizeStoreKeyword(keyword) {
+    return keyword
+        .trim()
+        .replace(/\s+/g, '')
+        .replace(/(역|지점|점)$/g, '');
+}
+function toBooleanYn(value) {
+    const normalized = toStringValue(value).trim().toUpperCase();
+    return normalized === 'Y' || normalized === 'TRUE' || normalized === '1';
+}
+function toRawProduct(input) {
+    if (!input || typeof input !== 'object') {
+        return {};
+    }
+    const record = input;
+    if (record.field && typeof record.field === 'object') {
+        return record.field;
+    }
+    return record;
+}
+function normalizeProduct(raw) {
+    return {
+        productNo: toStringValue(raw.prdNo),
+        itemCode: toStringValue(raw.itemCd),
+        itemName: toStringValue(raw.itemOnm),
+        salePrice: toNumber(raw.onlinePrice),
+        originalPrice: toNumber(raw.onlineCost),
+        imageUrl: toStringValue(raw.repImgUrl),
+        eventName: toStringValue(raw.eventGbnNm),
+        itemType: toStringValue(raw.itemGbnNm),
+        makerName: toStringValue(raw.makerNm),
+        reviewScore: raw.avgEvalScore === undefined ? null : toNumber(raw.avgEvalScore),
+        reviewCount: toNumber(raw.productReviewCnt),
+    };
+}
+function normalizeProducts(items) {
+    return items
+        .map(toRawProduct)
+        .map(normalizeProduct)
+        .filter((item) => item.itemCode.length > 0 || item.itemName.length > 0);
+}
+function normalizeStore(raw) {
+    const address1 = toStringValue(raw.addr1);
+    const address2 = toStringValue(raw.addr2);
+    const mergedAddress = `${address1} ${address2}`.trim();
+    return {
+        storeCode: toStringValue(raw.storeCode || raw.storeCd || raw.strCd || raw.storCd || raw.shopCd),
+        storeName: toStringValue(raw.storeName || raw.storeNm || raw.strNm || raw.storNm || raw.shopNm),
+        address: toStringValue(raw.address || raw.addr || raw.roadAddr || raw.shopAddr) || mergedAddress,
+        latitude: toNumber(raw.latitude || raw.storeLat || raw.lat || raw.yPos || raw.y || raw.yCoord),
+        longitude: toNumber(raw.longitude || raw.storeLon || raw.lng || raw.xPos || raw.x || raw.xCoord),
+        pickupEnabled: toBooleanYn(raw.pickupEnabled || raw.pickupYn),
+        deliveryEnabled: toBooleanYn(raw.deliveryEnabled || raw.deliveryYn || raw.dlvyYn),
+        closeYn: toStringValue(raw.closeYn || raw.storeCloseYn || raw.closeYN || raw.clsYn),
+    };
+}
+function normalizeStockProductMeta(raw) {
+    return {
+        productNo: toStringValue(raw.prdNo),
+        itemCode: toStringValue(raw.itemCd),
+        itemName: toStringValue(raw.itemOnm),
+        smCode: toStringValue(raw.smCd),
+        stockManagementCode: toStringValue(raw.stokMngCd),
+        stockManagementQuantity: toNumber(raw.stokMngQty),
+        stockApplicationRate: toStringValue(raw.stockApplicationRate),
+    };
+}
+function normalizeStores(items) {
+    return items
+        .map((item) => {
+        if (!item || typeof item !== 'object') {
+            return {};
+        }
+        const record = item;
+        if (record.field && typeof record.field === 'object') {
+            return record.field;
+        }
+        return record;
+    })
+        .map(normalizeStore)
+        .filter((store) => store.storeCode.length > 0 || store.storeName.length > 0);
+}
+async function requestSevenElevenJson(path, method, body, options = {}) {
+    const { timeout = 15000 } = options;
+    const url = `${SEVENELEVEN_API.BASE_URL}${path}`;
+    return fetchJson(url, {
+        method,
+        timeout,
+        headers: SEVENELEVEN_DEFAULT_HEADERS,
+        body: method === 'POST' ? JSON.stringify(body || {}) : undefined,
+    });
+}
+export async function searchSevenElevenProducts(params, options = {}) {
+    const { query, page = 1, size = 20 } = params;
+    const pageNo = Math.max(Math.trunc(page) - 1, 0);
+    const pageSize = Math.max(Math.trunc(size), 1);
+    const response = await requestSevenElevenJson(SEVENELEVEN_API.SEARCH_GOODS_PATH, 'POST', {
+        // 공개 검색 엔드포인트는 pageNo/pageSize만 안정적으로 동작한다.
+        // sort를 함께 보내면 빈 결과가 내려오는 케이스가 확인되어 제외한다.
+        query,
+        pageNo,
+        pageSize,
+    }, options);
+    const data = response.data || {};
+    const queryResult = data.SearchQueryResult;
+    const collections = queryResult?.Collection || [];
+    const collectionIds = collections.map((item) => item.CollectionId || '').filter((id) => id.length > 0);
+    let totalCount = 0;
+    const allDocuments = [];
+    for (const collection of collections) {
+        totalCount += toNumber(collection.Documentset?.totalCount);
+        allDocuments.push(...(collection.Documentset?.Document || []));
+    }
+    const collectionProducts = normalizeProducts(allDocuments);
+    const contentProducts = normalizeProducts(Array.isArray(data.content) ? data.content : []);
+    const products = (collectionProducts.length > 0 ? collectionProducts : contentProducts).slice(0, pageSize);
+    return {
+        query: queryResult?.query || query,
+        totalCount,
+        products,
+        collectionIds,
+    };
+}
+export async function fetchSevenElevenStoresByKeyword(params, options = {}) {
+    const { keyword, limit = 20 } = params;
+    const query = normalizeStoreKeyword(keyword) || keyword.trim();
+    const safeLimit = Number.isFinite(limit) ? Math.trunc(limit) : 20;
+    const listCount = Math.max(1, Math.min(safeLimit, 9999));
+    const response = await requestSevenElevenJson(SEVENELEVEN_API.SEARCH_STORE_PATH, 'POST', {
+        collection: 'store',
+        query,
+        sort: 'Date/desc',
+        listCount,
+    }, options);
+    const data = response.data || {};
+    const queryResult = data.SearchQueryResult;
+    const collections = queryResult?.Collection || [];
+    let totalCount = 0;
+    const allDocuments = [];
+    for (const collection of collections) {
+        totalCount += toNumber(collection.Documentset?.totalCount);
+        allDocuments.push(...(collection.Documentset?.Document || []));
+    }
+    const stores = normalizeStores(allDocuments);
+    return {
+        query: queryResult?.query || query,
+        totalCount,
+        stores,
+    };
+}
+export async function fetchSevenElevenSearchPopwords(label = 'home', options = {}) {
+    const encodedLabel = encodeURIComponent(label);
+    const response = await requestSevenElevenJson(`${SEVENELEVEN_API.SEARCH_POPWORD_PATH}?label=${encodedLabel}`, 'POST', {}, options);
+    const { data } = response;
+    if (Array.isArray(data)) {
+        return data.map((item) => toStringValue(item)).filter((item) => item.length > 0);
+    }
+    if (!data || typeof data !== 'object') {
+        return [];
+    }
+    const record = data;
+    const candidates = [record.keywords, record.popwords, record.wordList, record.list];
+    for (const candidate of candidates) {
+        if (!Array.isArray(candidate)) {
+            continue;
+        }
+        const values = candidate
+            .map((item) => {
+            if (typeof item === 'string') {
+                return item;
+            }
+            if (item && typeof item === 'object') {
+                const value = item;
+                return toStringValue(value.keyword || value.word || value.text || value.name);
+            }
+            return '';
+        })
+            .filter((item) => item.length > 0);
+        if (values.length > 0) {
+            return values;
+        }
+    }
+    return [];
+}
+export async function fetchSevenElevenStockProductMeta(itemCode, options = {}) {
+    const { timeout = 15000 } = 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, {
+        method: 'GET',
+        timeout,
+        headers: {
+            Accept: SEVENELEVEN_DEFAULT_HEADERS.Accept,
+            'User-Agent': SEVENELEVEN_DEFAULT_HEADERS['User-Agent'],
+        },
+    });
+    const productMeta = normalizeStockProductMeta(response);
+    if (productMeta.itemCode.length === 0 || productMeta.smCode.length === 0) {
+        return null;
+    }
+    return productMeta;
+}
+function normalizeExhibitions(items) {
+    return items
+        .map((item) => {
+        const value = (item || {});
+        const productList = Array.isArray(value.exhibitionProductList) ? value.exhibitionProductList : [];
+        return {
+            exhibitionIdx: toNumber(value.exhibitionIdx),
+            exhibitionName: toStringValue(value.exhibitionName),
+            startDate: toStringValue(value.exhibitionStartDate),
+            endDate: toStringValue(value.exhibitionEndDate),
+            productCount: productList.length,
+        };
+    })
+        .filter((item) => item.exhibitionIdx > 0 || item.exhibitionName.length > 0);
+}
+function extractContentArray(data) {
+    if (Array.isArray(data)) {
+        return data;
+    }
+    if (!data || typeof data !== 'object') {
+        return [];
+    }
+    const record = data;
+    if (Array.isArray(record.content)) {
+        return record.content;
+    }
+    if (Array.isArray(record.list)) {
+        return record.list;
+    }
+    return [];
+}
+export async function fetchSevenElevenCatalogSnapshot(options = {}) {
+    const { includeIssues = true, includeExhibition = true, timeout = 15000 } = options;
+    const tasks = [
+        requestSevenElevenJson(SEVENELEVEN_API.PRODUCT_PAGES_PATH, 'GET', null, { timeout }),
+        includeIssues
+            ? requestSevenElevenJson(SEVENELEVEN_API.PRODUCT_ISSUES_PATH, 'GET', null, { timeout })
+            : Promise.resolve({ data: { content: [] } }),
+        includeExhibition
+            ? requestSevenElevenJson(SEVENELEVEN_API.EXHIBITION_MAIN_PATH, 'GET', null, { timeout })
+            : Promise.resolve({ data: [] }),
+    ];
+    const [pagesResult, issuesResult, exhibitionsResult] = await Promise.allSettled(tasks);
+    const pagesData = pagesResult.status === 'fulfilled' ? pagesResult.value.data : [];
+    const issuesData = issuesResult.status === 'fulfilled' ? issuesResult.value.data : [];
+    const exhibitionData = exhibitionsResult.status === 'fulfilled' ? exhibitionsResult.value.data : [];
+    return {
+        pages: normalizeProducts(extractContentArray(pagesData)),
+        issues: normalizeProducts(extractContentArray(issuesData)),
+        exhibitions: normalizeExhibitions(extractContentArray(exhibitionData)),
+    };
+}
+/* c8 ignore stop */

package/dist/services/seveneleven/index.js

@@ -0,0 +1,30 @@
+/**
+ * 세븐일레븐 서비스 프로바이더
+ */
+import { createSearchProductsTool } from './tools/searchProducts.js';
+import { createSearchStoresTool } from './tools/searchStores.js';
+import { createCheckInventoryTool } from './tools/checkInventory.js';
+import { createGetSearchPopwordsTool } from './tools/getSearchPopwords.js';
+import { createGetCatalogSnapshotTool } from './tools/getCatalogSnapshot.js';
+const SEVENELEVEN_METADATA = {
+    id: 'seveneleven',
+    name: '세븐일레븐',
+    version: '1.0.0',
+    description: '세븐일레븐 공개 상품/검색/카탈로그 조회 서비스',
+};
+class SevenElevenService {
+    metadata = SEVENELEVEN_METADATA;
+    getTools() {
+        return [
+            createSearchProductsTool(),
+            createSearchStoresTool(),
+            createCheckInventoryTool(),
+            createGetSearchPopwordsTool(),
+            createGetCatalogSnapshotTool(),
+        ];
+    }
+}
+export function createSevenElevenService() {
+    return new SevenElevenService();
+}
+export * from './types.js';

package/dist/services/seveneleven/inventory.js

@@ -0,0 +1,302 @@
+/**
+ * 세븐일레븐 재고 조회 클라이언트
+ *
+ * 상품 검색 + 매장 검색 + 재고 API를 조합하여 재고 정보를 제공합니다.
+ * 재고 API가 암호화로 차단된 경우에도 상품/매장 정보를 graceful하게 반환합니다.
+ */
+/* c8 ignore start */
+import { fetchJson, HttpError } from '../../utils/http.js';
+import { SEVENELEVEN_API } from './api.js';
+import { fetchSevenElevenStockProductMeta, fetchSevenElevenStoresByKeyword, } from './client.js';
+import { pickBestSevenElevenProduct, searchSevenElevenProductsWithVariants } from './productKeyword.js';
+const SEVENELEVEN_DEFAULT_HEADERS = {
+    Accept: 'application/json, text/plain, */*',
+    'Content-Type': 'application/json',
+    'User-Agent': 'Mozilla/5.0 (Linux; Android 15)',
+};
+function toNumber(value) {
+    if (typeof value === 'number') {
+        return Number.isFinite(value) ? value : 0;
+    }
+    if (typeof value === 'string') {
+        const parsed = Number.parseFloat(value);
+        return Number.isFinite(parsed) ? parsed : 0;
+    }
+    return 0;
+}
+function toStringValue(value) {
+    return typeof value === 'string' ? value : '';
+}
+function normalizeStockStore(raw) {
+    return {
+        storeCode: toStringValue(raw.storeCd),
+        storeName: '',
+        address: '',
+        latitude: 0,
+        longitude: 0,
+        stockQuantity: toNumber(raw.stock),
+        isSoldOut: toNumber(raw.stock) <= 0,
+        distanceM: null,
+    };
+}
+function tryParseJsonObject(text) {
+    if (text.trim().length === 0) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(text);
+        return typeof parsed === 'object' && parsed !== null ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function toNullableNumber(value) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === 'string' && value.trim().length > 0) {
+        const parsed = Number.parseFloat(value);
+        return Number.isFinite(parsed) ? parsed : null;
+    }
+    return null;
+}
+function normalizeEnvelopeError(response) {
+    const hasErrorFlag = response.success === false;
+    const hasErrorCode = typeof response.code === 'number' && (response.code < 200 || response.code >= 300);
+    const hasErrorMessage = typeof response.message === 'string' && response.message.trim().length > 0;
+    if (response.success === true && !hasErrorCode) {
+        return null;
+    }
+    if (!hasErrorFlag && !hasErrorCode && !hasErrorMessage) {
+        return null;
+    }
+    return {
+        cause: 'api',
+        httpStatus: null,
+        code: toNullableNumber(response.code),
+        message: typeof response.message === 'string' ? response.message : '재고 API가 오류를 반환했습니다.',
+        raw: JSON.stringify(response),
+    };
+}
+function normalizeStockError(error) {
+    if (error instanceof HttpError) {
+        const parsedBody = tryParseJsonObject(error.bodyText);
+        return {
+            cause: 'api',
+            httpStatus: error.status,
+            code: toNullableNumber(parsedBody?.code),
+            message: typeof parsedBody?.message === 'string' && parsedBody.message.trim().length > 0
+                ? parsedBody.message
+                : error.message,
+            raw: error.bodyText.trim().length > 0 ? error.bodyText : null,
+        };
+    }
+    if (error instanceof Error) {
+        return {
+            cause: 'network',
+            httpStatus: null,
+            code: null,
+            message: error.message,
+            raw: null,
+        };
+    }
+    return {
+        cause: 'unknown',
+        httpStatus: null,
+        code: null,
+        message: '알 수 없는 재고 API 오류',
+        raw: null,
+    };
+}
+function haversineDistanceM(lat1, lon1, lat2, lon2) {
+    const R = 6371000;
+    const toRad = (deg) => (deg * Math.PI) / 180;
+    const dLat = toRad(lat2 - lat1);
+    const dLon = toRad(lon2 - lon1);
+    const a = Math.sin(dLat / 2) * Math.sin(dLat / 2) +
+        Math.cos(toRad(lat1)) * Math.cos(toRad(lat2)) * Math.sin(dLon / 2) * Math.sin(dLon / 2);
+    return R * 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+}
+function attachDistanceToStockStores(stores, refLat, refLon) {
+    return stores.map((store) => {
+        if (store.latitude === 0 && store.longitude === 0) {
+            return store;
+        }
+        return {
+            ...store,
+            distanceM: Math.round(haversineDistanceM(refLat, refLon, store.latitude, store.longitude)),
+        };
+    });
+}
+function normalizeStoreKeyword(keyword) {
+    return keyword
+        .trim()
+        .replace(/\s+/g, '')
+        .replace(/(역|지점|점)$/g, '')
+        .toLowerCase();
+}
+function tokenizeStoreKeyword(keyword) {
+    return keyword
+        .trim()
+        .split(/\s+/)
+        .map((token) => normalizeStoreKeyword(token))
+        .filter((token) => token.length > 0);
+}
+function filterStoresByKeyword(stores, keyword) {
+    if (!keyword || keyword.trim().length === 0) {
+        return stores;
+    }
+    const normalized = normalizeStoreKeyword(keyword);
+    const exactMatched = stores.filter((store) => {
+        const nameNorm = store.storeName.replace(/\s+/g, '').toLowerCase();
+        const addrNorm = store.address.replace(/\s+/g, '').toLowerCase();
+        return nameNorm.includes(normalized) || addrNorm.includes(normalized);
+    });
+    if (exactMatched.length > 0) {
+        return exactMatched;
+    }
+    const tokens = tokenizeStoreKeyword(keyword).filter((token) => token.length >= 2);
+    if (tokens.length === 0) {
+        return stores;
+    }
+    const tokenMatched = stores.filter((store) => {
+        const combined = `${store.storeName} ${store.address}`.replace(/\s+/g, '').toLowerCase();
+        return tokens.every((token) => combined.includes(token));
+    });
+    return tokenMatched.length > 0 ? tokenMatched : stores;
+}
+async function tryStockApi(stockProduct, stores, options = {}) {
+    const { timeout = 15000 } = options;
+    const url = `${SEVENELEVEN_API.BASE_URL}${SEVENELEVEN_API.REAL_STOCK_MULTI_PATH}/01/stocks`;
+    const payload = {
+        smCd: stockProduct.smCode,
+        stokMngCd: stockProduct.stockManagementCode,
+        stokMngQty: stockProduct.stockManagementQuantity,
+        stockApplicationRate: stockProduct.stockApplicationRate,
+        storeList: stores.map((store) => store.storeCode).filter((storeCode) => storeCode.length > 0),
+    };
+    if (payload.smCd.length === 0 || payload.stokMngCd.length === 0 || payload.storeList.length === 0) {
+        return { stores: null, error: null };
+    }
+    try {
+        const response = await fetchJson(url, {
+            method: 'POST',
+            timeout,
+            headers: SEVENELEVEN_DEFAULT_HEADERS,
+            body: JSON.stringify(payload),
+        });
+        const responseError = normalizeEnvelopeError(response);
+        if (responseError) {
+            return { stores: null, error: responseError };
+        }
+        const data = response.data || {};
+        const rawStores = Array.isArray(data.storeList) ? data.storeList : [];
+        return {
+            stores: rawStores
+                .map((item) => normalizeStockStore(item))
+                .filter((store) => store.storeCode.length > 0),
+            error: null,
+        };
+    }
+    catch (error) {
+        return {
+            stores: null,
+            error: normalizeStockError(error),
+        };
+    }
+}
+export async function checkSevenElevenInventory(params, options = {}) {
+    const { productKeyword, storeKeyword, storeLimit = 20 } = params;
+    // 1) 상품 검색
+    const productResult = await searchSevenElevenProductsWithVariants(productKeyword, options);
+    const firstProduct = pickBestSevenElevenProduct(productResult.products, productKeyword) ||
+        productResult.products.find((p) => p.itemCode.length > 0) ||
+        productResult.products[0] ||
+        null;
+    // 2) 매장 검색
+    const storeResult = await fetchSevenElevenStoresByKeyword({ keyword: storeKeyword, limit: 100 }, options);
+    const matchedStores = filterStoresByKeyword(storeResult.stores, storeKeyword);
+    // 3) 재고 API 시도 (실패 시 graceful fallback)
+    let stockStores = null;
+    let stockError = null;
+    if (firstProduct && firstProduct.itemCode.length > 0) {
+        try {
+            const stockProduct = await fetchSevenElevenStockProductMeta(firstProduct.itemCode, options);
+            if (stockProduct) {
+                const stockAttempt = await tryStockApi(stockProduct, matchedStores, options);
+                stockStores = stockAttempt.stores;
+                stockError = stockAttempt.error;
+            }
+        }
+        catch (error) {
+            stockError = normalizeStockError(error);
+        }
+    }
+    // 4) 결과 조합
+    let resultStores;
+    let stockAvailable;
+    if (stockStores !== null && stockStores.length > 0) {
+        stockAvailable = true;
+        const stockMap = new Map(stockStores.map((store) => [store.storeCode, store]));
+        resultStores = matchedStores.map((store) => {
+            const stockStore = stockMap.get(store.storeCode);
+            return {
+                storeCode: store.storeCode,
+                storeName: store.storeName,
+                address: store.address,
+                latitude: store.latitude,
+                longitude: store.longitude,
+                stockQuantity: stockStore?.stockQuantity ?? -1,
+                isSoldOut: stockStore ? stockStore.isSoldOut : false,
+                distanceM: null,
+            };
+        });
+    }
+    else {
+        stockAvailable = false;
+        resultStores = matchedStores.map((store) => ({
+            storeCode: store.storeCode,
+            storeName: store.storeName,
+            address: store.address,
+            latitude: store.latitude,
+            longitude: store.longitude,
+            stockQuantity: -1,
+            isSoldOut: false,
+            distanceM: null,
+        }));
+    }
+    // 거리 계산: 첫 번째 매장 좌표를 기준으로 정렬
+    const refStore = matchedStores.find((s) => s.latitude !== 0 && s.longitude !== 0);
+    if (refStore) {
+        resultStores = attachDistanceToStockStores(resultStores, refStore.latitude, refStore.longitude);
+        resultStores.sort((a, b) => {
+            if (a.distanceM === null && b.distanceM === null)
+                return 0;
+            if (a.distanceM === null)
+                return 1;
+            if (b.distanceM === null)
+                return -1;
+            return a.distanceM - b.distanceM;
+        });
+    }
+    const limited = resultStores.slice(0, storeLimit);
+    const inStockCount = stockAvailable ? limited.filter((s) => s.stockQuantity > 0).length : 0;
+    return {
+        productKeyword,
+        product: firstProduct
+            ? {
+                itemCode: firstProduct.itemCode,
+                itemName: firstProduct.itemName,
+                salePrice: firstProduct.salePrice,
+                imageUrl: firstProduct.imageUrl,
+            }
+            : null,
+        stockAvailable,
+        stockError,
+        totalStoreCount: resultStores.length,
+        inStockStoreCount: inStockCount,
+        stores: limited,
+    };
+}
+/* c8 ignore stop */