ebay-mcp-remote-edition 3.1.2 → 3.3.0

package/build/validation/providers/ebay-sold.js

@@ -0,0 +1,216 @@
+import axios from 'axios';
+import { buildResolvedSoldQueryPlan } from './query-utils.js';
+function round(value) {
+    return Math.round(value * 100) / 100;
+}
+function normalizePrice(value) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return round(value);
+    }
+    if (typeof value === 'string') {
+        const parsed = Number(value.replace(/[^0-9.-]+/g, ''));
+        if (Number.isFinite(parsed)) {
+            return round(parsed);
+        }
+    }
+    return null;
+}
+function parseSoldDate(value) {
+    if (!value) {
+        return null;
+    }
+    const parsed = new Date(value);
+    if (Number.isFinite(parsed.getTime())) {
+        return parsed.toISOString();
+    }
+    return null;
+}
+function normalizeProducts(products) {
+    return (products ?? []).slice(0, 10).map((product) => ({
+        title: product.title?.trim() ?? 'Untitled sold listing',
+        soldAt: parseSoldDate(product.date_sold),
+        priceUsd: normalizePrice(product.sale_price),
+        itemUrl: typeof product.link === 'string' ? product.link : null,
+    }));
+}
+function bucketSoldVelocity(soldItemsSample, requestTimestamp) {
+    const requestDate = new Date(requestTimestamp);
+    if (!Number.isFinite(requestDate.getTime())) {
+        return {
+            day1Sold: null,
+            day2Sold: null,
+            day3Sold: null,
+            day4Sold: null,
+            day5Sold: null,
+            daysTracked: null,
+        };
+    }
+    const buckets = [0, 0, 0, 0, 0];
+    let maxTrackedDay = 0;
+    for (const item of soldItemsSample) {
+        if (!item.soldAt) {
+            continue;
+        }
+        const soldDate = new Date(item.soldAt);
+        if (!Number.isFinite(soldDate.getTime()) || soldDate.getTime() > requestDate.getTime()) {
+            continue;
+        }
+        const diffDays = Math.floor((requestDate.getTime() - soldDate.getTime()) / (24 * 60 * 60 * 1000));
+        if (diffDays >= 0 && diffDays < 5) {
+            buckets[diffDays] += 1;
+            maxTrackedDay = Math.max(maxTrackedDay, diffDays + 1);
+        }
+    }
+    return {
+        day1Sold: buckets[0],
+        day2Sold: buckets[1],
+        day3Sold: buckets[2],
+        day4Sold: buckets[3],
+        day5Sold: buckets[4],
+        daysTracked: maxTrackedDay > 0 ? maxTrackedDay : null,
+    };
+}
+function scoreSoldConfidence(soldResultsCount, soldItemsSample) {
+    const datedItems = soldItemsSample.filter((item) => item.soldAt !== null).length;
+    if ((soldResultsCount ?? 0) >= 20 && datedItems >= 3) {
+        return 'High';
+    }
+    if ((soldResultsCount ?? 0) >= 8) {
+        return 'Medium';
+    }
+    return 'Low';
+}
+function createEmptySoldSignals(query, queryCandidates = [], status, errorMessage) {
+    return {
+        provider: 'third_party_sold_api',
+        confidence: 'Low',
+        soldResultsCount: null,
+        soldAveragePriceUsd: null,
+        soldMedianPriceUsd: null,
+        soldMinPriceUsd: null,
+        soldMaxPriceUsd: null,
+        soldItemsSample: [],
+        soldVelocity: {
+            day1Sold: null,
+            day2Sold: null,
+            day3Sold: null,
+            day4Sold: null,
+            day5Sold: null,
+            daysTracked: null,
+        },
+        query,
+        queryCandidates,
+        selectedQuery: query ?? undefined,
+        selectedQueryTier: query ? 1 : null,
+        responseUrl: null,
+        status,
+        ...(errorMessage ? { errorMessage } : {}),
+    };
+}
+export async function getEbaySoldValidationSignals(request) {
+    const soldApiUrl = process.env.SOLD_ITEMS_API_URL?.trim();
+    const soldApiKey = process.env.SOLD_ITEMS_API_KEY?.trim();
+    const { queryPlan, queryResolution } = buildResolvedSoldQueryPlan(request);
+    const queryCandidates = queryPlan.map((candidate) => candidate.query);
+    const query = queryCandidates[0] ?? null;
+    const queryDiagnostics = [];
+    if (!soldApiUrl || !soldApiKey || !query) {
+        return {
+            ...createEmptySoldSignals(query, queryCandidates, 'unavailable'),
+            queryDiagnostics,
+            queryResolution,
+        };
+    }
+    try {
+        const endpoint = soldApiUrl.endsWith('/findCompletedItems')
+            ? soldApiUrl
+            : `${soldApiUrl.replace(/\/$/, '')}/findCompletedItems`;
+        const host = new URL(endpoint).host;
+        let selectedResult = {
+            ...createEmptySoldSignals(query, queryCandidates, 'unavailable'),
+            queryDiagnostics,
+            queryResolution,
+        };
+        let lastErrorMessage;
+        for (const [index, candidate] of queryCandidates.entries()) {
+            try {
+                const response = await axios.post(endpoint, {
+                    keywords: candidate,
+                    excluded_keywords: 'set lot bundle photocard fanmade replica unofficial',
+                    max_search_results: 120,
+                    remove_outliers: true,
+                    site_id: '0',
+                }, {
+                    timeout: 30000,
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'x-rapidapi-key': soldApiKey,
+                        'x-rapidapi-host': host,
+                    },
+                });
+                const data = response.data;
+                const soldItemsSample = normalizeProducts(data.products);
+                const soldVelocity = bucketSoldVelocity(soldItemsSample, request.timestamp);
+                const soldResultsCount = typeof data.results === 'number' && Number.isFinite(data.results) ? data.results : null;
+                queryDiagnostics.push({
+                    query: candidate,
+                    tier: index + 1,
+                    family: queryPlan[index]?.family,
+                    soldResultsCount,
+                    status: data.success === false ? 'error' : 'ok',
+                });
+                selectedResult = {
+                    provider: 'third_party_sold_api',
+                    confidence: scoreSoldConfidence(soldResultsCount, soldItemsSample),
+                    soldResultsCount,
+                    soldAveragePriceUsd: normalizePrice(data.average_price),
+                    soldMedianPriceUsd: normalizePrice(data.median_price),
+                    soldMinPriceUsd: normalizePrice(data.min_price),
+                    soldMaxPriceUsd: normalizePrice(data.max_price),
+                    soldItemsSample,
+                    soldVelocity,
+                    query: candidate,
+                    queryCandidates,
+                    queryDiagnostics: [...queryDiagnostics],
+                    selectedQuery: candidate,
+                    selectedQueryTier: index + 1,
+                    responseUrl: typeof data.response_url === 'string' ? data.response_url : null,
+                    status: data.success === false ? 'error' : 'ok',
+                    queryResolution,
+                };
+                if ((soldResultsCount ?? 0) >= 5) {
+                    break;
+                }
+            }
+            catch (error) {
+                lastErrorMessage = error instanceof Error ? error.message : String(error);
+                queryDiagnostics.push({
+                    query: candidate,
+                    tier: index + 1,
+                    family: queryPlan[index]?.family,
+                    soldResultsCount: null,
+                    status: 'error',
+                    note: lastErrorMessage,
+                });
+            }
+        }
+        if (selectedResult.status === 'unavailable' && queryDiagnostics.length > 0) {
+            return {
+                ...createEmptySoldSignals(query, queryCandidates, 'error', lastErrorMessage),
+                queryDiagnostics,
+                queryResolution,
+            };
+        }
+        return {
+            ...selectedResult,
+            queryResolution,
+        };
+    }
+    catch (error) {
+        return {
+            ...createEmptySoldSignals(query, queryCandidates, 'error', error instanceof Error ? error.message : String(error)),
+            queryDiagnostics,
+            queryResolution,
+        };
+    }
+}

package/build/validation/providers/ebay.js

@@ -0,0 +1,170 @@
+import axios from 'axios';
+import { getBaseUrl } from '../../config/environment.js';
+import { buildResolvedBrowseQueryPlan } from './query-utils.js';
+function round(value) {
+    return Math.round(value * 100) / 100;
+}
+export function buildEbayValidationQueries(request) {
+    return buildResolvedBrowseQueryPlan(request).queryPlan.map((candidate) => candidate.query);
+}
+function deriveTrend(current, previous, fallback) {
+    if (current === null || previous === null || previous <= 0) {
+        return fallback || 'Stable';
+    }
+    const deltaRatio = (current - previous) / previous;
+    if (deltaRatio >= 0.08)
+        return 'Rising';
+    if (deltaRatio <= -0.08)
+        return 'Falling';
+    return 'Stable';
+}
+function median(values) {
+    if (values.length === 0)
+        return null;
+    const sorted = [...values].sort((a, b) => a - b);
+    const middle = Math.floor(sorted.length / 2);
+    if (sorted.length % 2 === 0) {
+        return (sorted[middle - 1] + sorted[middle]) / 2;
+    }
+    return sorted[middle];
+}
+function getAxiosFailureDebug(error) {
+    if (!axios.isAxiosError(error)) {
+        return {
+            responseStatus: null,
+            responseBodyExcerpt: null,
+        };
+    }
+    const responseStatus = error.response?.status ?? null;
+    const rawBody = error.response?.data;
+    if (rawBody === undefined) {
+        return {
+            responseStatus,
+            responseBodyExcerpt: null,
+        };
+    }
+    const bodyText = typeof rawBody === 'string' ? rawBody : JSON.stringify(rawBody, null, 2);
+    return {
+        responseStatus,
+        responseBodyExcerpt: bodyText.slice(0, 500),
+    };
+}
+export async function getEbayValidationSignals(api, request) {
+    const { queryPlan, queryResolution } = buildResolvedBrowseQueryPlan(request);
+    const queryCandidates = queryPlan.map((candidate) => candidate.query);
+    const ebayQuery = queryCandidates[0] ?? '';
+    const fallbackTrend = request.validation.currentMetrics.marketPriceTrend || 'Stable';
+    const emptyResult = {
+        avgWatchersPerListing: null,
+        preOrderListingsCount: null,
+        marketPriceUsd: null,
+        avgShippingCostUsd: null,
+        competitionLevel: null,
+        marketPriceTrend: fallbackTrend,
+        ebayQuery,
+        queryCandidates,
+        selectedQuery: ebayQuery || undefined,
+        selectedQueryTier: ebayQuery ? 1 : null,
+        queryDiagnostics: [],
+        selectionReason: queryCandidates.length
+            ? 'Cleaned browse candidates were generated, but none have been evaluated yet.'
+            : 'No valid browse query candidates were generated after sanitization and semantic filtering.',
+        sampleSize: 0,
+        soldVelocity: {
+            day1Sold: request.validation.currentMetrics.day1Sold,
+            day2Sold: request.validation.currentMetrics.day2Sold,
+            day3Sold: request.validation.currentMetrics.day3Sold,
+            day4Sold: request.validation.currentMetrics.day4Sold,
+            day5Sold: request.validation.currentMetrics.day5Sold,
+            daysTracked: request.validation.currentMetrics.daysTracked,
+        },
+        queryResolution,
+    };
+    if (queryCandidates.length === 0) {
+        return emptyResult;
+    }
+    try {
+        const environment = api.getAuthClient().getConfig().environment;
+        const browseUrl = new URL('/buy/browse/v1/item_summary/search', getBaseUrl(environment)).toString();
+        let selectedResult = emptyResult;
+        let bestScore = -1;
+        const queryDiagnostics = [];
+        for (const [index, query] of queryCandidates.entries()) {
+            const response = await api.getAuthClient().getWithFullUrl(browseUrl, {
+                q: query,
+                limit: 25,
+                sort: 'newlyListed',
+            });
+            const itemSummaries = response.itemSummaries ?? [];
+            const prices = itemSummaries
+                .map((item) => Number(item.price?.value ?? Number.NaN))
+                .filter((value) => Number.isFinite(value) && value > 0);
+            const shipping = itemSummaries
+                .map((item) => Number(item.shippingOptions?.[0]?.shippingCost?.value ?? Number.NaN))
+                .filter((value) => Number.isFinite(value) && value >= 0);
+            const marketPriceUsd = median(prices);
+            const avgShippingCostUsd = shipping.length > 0
+                ? shipping.reduce((sum, value) => sum + value, 0) / shipping.length
+                : null;
+            const totalListings = typeof response.total === 'number' && Number.isFinite(response.total)
+                ? response.total
+                : itemSummaries.length;
+            const attemptScore = Math.max(itemSummaries.length, totalListings);
+            queryDiagnostics.push({
+                query,
+                tier: index + 1,
+                family: queryPlan[index]?.family,
+                itemSummaryCount: itemSummaries.length,
+                totalListings,
+            });
+            if (attemptScore <= bestScore) {
+                if (itemSummaries.length >= 5 || totalListings >= 5) {
+                    break;
+                }
+                continue;
+            }
+            bestScore = attemptScore;
+            selectedResult = {
+                avgWatchersPerListing: null,
+                preOrderListingsCount: totalListings,
+                marketPriceUsd: marketPriceUsd === null ? null : round(marketPriceUsd),
+                avgShippingCostUsd: avgShippingCostUsd === null ? null : round(avgShippingCostUsd),
+                competitionLevel: totalListings,
+                marketPriceTrend: deriveTrend(marketPriceUsd, request.validation.currentMetrics.marketPriceUsd, fallbackTrend),
+                ebayQuery: query,
+                queryCandidates,
+                selectedQuery: query,
+                selectedQueryTier: index + 1,
+                queryDiagnostics: [...queryDiagnostics],
+                selectionReason: itemSummaries.length >= 5 || totalListings >= 5
+                    ? 'Selected because this cleaned browse candidate produced sufficient listing depth.'
+                    : attemptScore > 0
+                        ? 'Selected as the strongest cleaned browse fallback after higher-priority candidates returned weaker results.'
+                        : 'All cleaned browse candidates seen so far returned zero results; keeping the highest-priority candidate for traceability.',
+                sampleSize: itemSummaries.length,
+                soldVelocity: emptyResult.soldVelocity,
+                queryResolution,
+            };
+            if (itemSummaries.length >= 5 || totalListings >= 5) {
+                break;
+            }
+        }
+        return {
+            ...selectedResult,
+            queryDiagnostics,
+            selectionReason: selectedResult.selectionReason ??
+                'Browse selection completed without a stronger candidate than the highest-priority cleaned query.',
+        };
+    }
+    catch (error) {
+        const failureDebug = getAxiosFailureDebug(error);
+        return {
+            ...emptyResult,
+            selectionReason: 'Browse query execution failed before result selection could complete; returning the cleaned fallback candidate set for debug traceability.',
+            errorMessage: error instanceof Error ? error.message : String(error),
+            responseStatus: failureDebug.responseStatus,
+            responseBodyExcerpt: failureDebug.responseBodyExcerpt,
+            queryResolution,
+        };
+    }
+}