ebay-mcp-remote-edition 3.2.0 → 3.3.1

package/build/api/listing-metadata/metadata.js

@@ -27,7 +27,7 @@ export class MetadataApi {
             return await this.client.get(`${this.basePath}/marketplace/${marketplaceId}/get_automotive_parts_compatibility_policies`, params);
         }
         catch (error) {
-            throw new Error(`Failed to get automotive parts compatibility policies: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            throw new Error(`Failed to get automotive parts compatibility policies: ${error instanceof Error ? error.message : 'Unknown error'}`, { cause: error });
         }
     }
     /**
@@ -49,7 +49,7 @@ export class MetadataApi {
             return await this.client.get(`${this.basePath}/marketplace/${marketplaceId}/get_category_policies`, params);
         }
         catch (error) {
-            throw new Error(`Failed to get category policies: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            throw new Error(`Failed to get category policies: ${error instanceof Error ? error.message : 'Unknown error'}`, { cause: error });
         }
     }
     /**
@@ -71,7 +71,7 @@ export class MetadataApi {
             return await this.client.get(`${this.basePath}/marketplace/${marketplaceId}/get_extended_producer_responsibility_policies`, params);
         }
         catch (error) {
-            throw new Error(`Failed to get extended producer responsibility policies: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            throw new Error(`Failed to get extended producer responsibility policies: ${error instanceof Error ? error.message : 'Unknown error'}`, { cause: error });
         }
     }
     /**
@@ -87,7 +87,7 @@ export class MetadataApi {
             return await this.client.get(`${this.basePath}/marketplace/${marketplaceId}/get_hazardous_materials_labels`);
         }
         catch (error) {
-            throw new Error(`Failed to get hazardous materials labels: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            throw new Error(`Failed to get hazardous materials labels: ${error instanceof Error ? error.message : 'Unknown error'}`, { cause: error });
         }
     }
     /**
@@ -109,7 +109,7 @@ export class MetadataApi {
             return await this.client.get(`${this.basePath}/marketplace/${marketplaceId}/get_item_condition_policies`, params);
         }
         catch (error) {
-            throw new Error(`Failed to get item condition policies: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            throw new Error(`Failed to get item condition policies: ${error instanceof Error ? error.message : 'Unknown error'}`, { cause: error });
         }
     }
     /**
@@ -131,7 +131,7 @@ export class MetadataApi {
             return await this.client.get(`${this.basePath}/marketplace/${marketplaceId}/get_listing_structure_policies`, params);
         }
         catch (error) {
-            throw new Error(`Failed to get listing structure policies: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            throw new Error(`Failed to get listing structure policies: ${error instanceof Error ? error.message : 'Unknown error'}`, { cause: error });
         }
     }
     /**
@@ -153,7 +153,7 @@ export class MetadataApi {
             return await this.client.get(`${this.basePath}/marketplace/${marketplaceId}/get_negotiated_price_policies`, params);
         }
         catch (error) {
-            throw new Error(`Failed to get negotiated price policies: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            throw new Error(`Failed to get negotiated price policies: ${error instanceof Error ? error.message : 'Unknown error'}`, { cause: error });
         }
     }
     /**
@@ -169,7 +169,7 @@ export class MetadataApi {
             return await this.client.get(`${this.basePath}/marketplace/${marketplaceId}/get_product_safety_labels`);
         }
         catch (error) {
-            throw new Error(`Failed to get product safety labels: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            throw new Error(`Failed to get product safety labels: ${error instanceof Error ? error.message : 'Unknown error'}`, { cause: error });
         }
     }
     /**
@@ -191,7 +191,7 @@ export class MetadataApi {
             return await this.client.get(`${this.basePath}/marketplace/${marketplaceId}/get_regulatory_policies`, params);
         }
         catch (error) {
-            throw new Error(`Failed to get regulatory policies: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            throw new Error(`Failed to get regulatory policies: ${error instanceof Error ? error.message : 'Unknown error'}`, { cause: error });
         }
     }
     /**
@@ -213,7 +213,7 @@ export class MetadataApi {
             return await this.client.get(`${this.basePath}/marketplace/${marketplaceId}/get_return_policies`, params);
         }
         catch (error) {
-            throw new Error(`Failed to get return policies: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            throw new Error(`Failed to get return policies: ${error instanceof Error ? error.message : 'Unknown error'}`, { cause: error });
         }
     }
     /**
@@ -235,7 +235,7 @@ export class MetadataApi {
             return await this.client.get(`${this.basePath}/marketplace/${marketplaceId}/get_shipping_cost_type_policies`, params);
         }
         catch (error) {
-            throw new Error(`Failed to get shipping cost type policies: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            throw new Error(`Failed to get shipping cost type policies: ${error instanceof Error ? error.message : 'Unknown error'}`, { cause: error });
         }
     }
     /**
@@ -257,7 +257,7 @@ export class MetadataApi {
             return await this.client.get(`${this.basePath}/marketplace/${marketplaceId}/get_classified_ad_policies`, params);
         }
         catch (error) {
-            throw new Error(`Failed to get classified ad policies: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            throw new Error(`Failed to get classified ad policies: ${error instanceof Error ? error.message : 'Unknown error'}`, { cause: error });
         }
     }
     /**
@@ -273,7 +273,7 @@ export class MetadataApi {
             return await this.client.get(`${this.basePath}/marketplace/${marketplaceId}/get_currencies`);
         }
         catch (error) {
-            throw new Error(`Failed to get currencies: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            throw new Error(`Failed to get currencies: ${error instanceof Error ? error.message : 'Unknown error'}`, { cause: error });
         }
     }
     /**
@@ -295,7 +295,7 @@ export class MetadataApi {
             return await this.client.get(`${this.basePath}/marketplace/${marketplaceId}/get_listing_type_policies`, params);
         }
         catch (error) {
-            throw new Error(`Failed to get listing type policies: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            throw new Error(`Failed to get listing type policies: ${error instanceof Error ? error.message : 'Unknown error'}`, { cause: error });
         }
     }
     /**
@@ -317,7 +317,7 @@ export class MetadataApi {
             return await this.client.get(`${this.basePath}/marketplace/${marketplaceId}/get_motors_listing_policies`, params);
         }
         catch (error) {
-            throw new Error(`Failed to get motors listing policies: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            throw new Error(`Failed to get motors listing policies: ${error instanceof Error ? error.message : 'Unknown error'}`, { cause: error });
         }
     }
     /**
@@ -339,7 +339,7 @@ export class MetadataApi {
             return await this.client.get(`${this.basePath}/marketplace/${marketplaceId}/get_shipping_policies`, params);
         }
         catch (error) {
-            throw new Error(`Failed to get shipping policies: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            throw new Error(`Failed to get shipping policies: ${error instanceof Error ? error.message : 'Unknown error'}`, { cause: error });
         }
     }
     /**
@@ -361,7 +361,7 @@ export class MetadataApi {
             return await this.client.get(`${this.basePath}/marketplace/${marketplaceId}/get_site_visibility_policies`, params);
         }
         catch (error) {
-            throw new Error(`Failed to get site visibility policies: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            throw new Error(`Failed to get site visibility policies: ${error instanceof Error ? error.message : 'Unknown error'}`, { cause: error });
         }
     }
     /**
@@ -377,7 +377,7 @@ export class MetadataApi {
             return await this.client.post(`${this.basePath}/compatibilities/get_compatibilities_by_specification`, specification);
         }
         catch (error) {
-            throw new Error(`Failed to get compatibilities by specification: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            throw new Error(`Failed to get compatibilities by specification: ${error instanceof Error ? error.message : 'Unknown error'}`, { cause: error });
         }
     }
     /**
@@ -393,7 +393,7 @@ export class MetadataApi {
             return await this.client.post(`${this.basePath}/compatibilities/get_compatibility_property_names`, data);
         }
         catch (error) {
-            throw new Error(`Failed to get compatibility property names: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            throw new Error(`Failed to get compatibility property names: ${error instanceof Error ? error.message : 'Unknown error'}`, { cause: error });
         }
     }
     /**
@@ -409,7 +409,7 @@ export class MetadataApi {
             return await this.client.post(`${this.basePath}/compatibilities/get_compatibility_property_values`, data);
         }
         catch (error) {
-            throw new Error(`Failed to get compatibility property values: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            throw new Error(`Failed to get compatibility property values: ${error instanceof Error ? error.message : 'Unknown error'}`, { cause: error });
         }
     }
     /**
@@ -425,7 +425,7 @@ export class MetadataApi {
             return await this.client.post(`${this.basePath}/compatibilities/get_multi_compatibility_property_values`, data);
         }
         catch (error) {
-            throw new Error(`Failed to get multi compatibility property values: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            throw new Error(`Failed to get multi compatibility property values: ${error instanceof Error ? error.message : 'Unknown error'}`, { cause: error });
         }
     }
     /**
@@ -441,7 +441,7 @@ export class MetadataApi {
             return await this.client.post(`${this.basePath}/compatibilities/get_product_compatibilities`, data);
         }
         catch (error) {
-            throw new Error(`Failed to get product compatibilities: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            throw new Error(`Failed to get product compatibilities: ${error instanceof Error ? error.message : 'Unknown error'}`, { cause: error });
         }
     }
     /**
@@ -457,7 +457,7 @@ export class MetadataApi {
             return await this.client.get(`${this.basePath}/country/${countryCode}/sales_tax_jurisdiction`);
         }
         catch (error) {
-            throw new Error(`Failed to get sales tax jurisdictions: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            throw new Error(`Failed to get sales tax jurisdictions: ${error instanceof Error ? error.message : 'Unknown error'}`, { cause: error });
         }
     }
     /**
@@ -479,7 +479,7 @@ export class MetadataApi {
             return await this.client.get(`${this.basePath}/marketplace/${marketplaceId}/get_product_compliance_policies`, params);
         }
         catch (error) {
-            throw new Error(`Failed to get product compliance policies: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            throw new Error(`Failed to get product compliance policies: ${error instanceof Error ? error.message : 'Unknown error'}`, { cause: error });
         }
     }
 }

package/build/auth/oauth.js

@@ -165,10 +165,10 @@ export class EbayOAuthClient {
             if (axios.isAxiosError(error) && error.response?.data) {
                 const data = error.response.data;
                 if (data.error_description) {
-                    throw new Error(data.error_description);
+                    throw new Error(data.error_description, { cause: error });
                 }
                 if (data.error) {
-                    throw new Error(data.error);
+                    throw new Error(data.error, { cause: error });
                 }
             }
             throw error;

package/build/auth/token-verifier.js

@@ -20,7 +20,7 @@ export class TokenVerifier {
                 this.metadata = response.data;
             }
             catch (error) {
-                throw new Error(`Failed to load OAuth server metadata: ${error instanceof Error ? error.message : 'Unknown error'}`);
+                throw new Error(`Failed to load OAuth server metadata: ${error instanceof Error ? error.message : 'Unknown error'}`, { cause: error });
             }
         }
         else {
@@ -104,7 +104,7 @@ export class TokenVerifier {
         }
         catch (error) {
             if (axios.isAxiosError(error)) {
-                throw new Error(`Token introspection failed: ${error.response?.data?.error_description || error.message}`);
+                throw new Error(`Token introspection failed: ${error.response?.data?.error_description || error.message}`, { cause: error });
             }
             throw error;
         }
@@ -150,7 +150,7 @@ export class TokenVerifier {
             };
         }
         catch (error) {
-            throw new Error(`JWT verification failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            throw new Error(`JWT verification failed: ${error instanceof Error ? error.message : 'Unknown error'}`, { cause: error });
         }
     }
     /**

package/build/server-http.js

@@ -429,6 +429,11 @@ function mountEnvRouter(hardcodedEnv, serverUrl, iconBaseUrl) {
         const storedTokens = validationRunnerUserId
             ? await authStore.getUserTokens(validationRunnerUserId, environment)
             : null;
+        const socialConfig = {
+            hasTwitterBearerToken: Boolean(process.env.TWITTER_BEARER_TOKEN?.trim()),
+            hasYoutubeApiKey: Boolean(process.env.YOUTUBE_API_KEY?.trim()),
+            hasRedditUserAgent: Boolean(process.env.REDDIT_USER_AGENT?.trim()),
+        };
         let authenticated = false;
         let authError = null;
         let tokenStatus = null;
@@ -467,7 +472,7 @@ function mountEnvRouter(hardcodedEnv, serverUrl, iconBaseUrl) {
                 });
             }
         }
-        res.json({
+        const healthResponse = {
             status: authenticated ? 'ok' : 'degraded',
             environment,
             validationRunnerUserId,
@@ -479,9 +484,21 @@ function mountEnvRouter(hardcodedEnv, serverUrl, iconBaseUrl) {
                 ebay: { available: true, implemented: true, confidence: 'medium' },
                 social: { available: false, implemented: false, confidence: 'low' },
                 chart: { available: false, implemented: false, confidence: 'low' },
+                socialConfig,
             },
             ...(authError ? { authError } : {}),
+        };
+        serverLogger.info('Validation health response emitted', {
+            environment,
+            path: req.originalUrl,
+            status: healthResponse.status,
+            version: getVersion(),
+            hasSocialConfigAtRoot: Object.prototype.hasOwnProperty.call(healthResponse, 'socialConfig'),
+            hasSocialConfigUnderProviders: Object.prototype.hasOwnProperty.call(healthResponse.providers, 'socialConfig'),
+            providerKeys: Object.keys(healthResponse.providers),
+            socialConfig,
         });
+        res.json(healthResponse);
     });
     // ── RFC 8414 – Authorization Server Metadata ──────────────────────────
     // For env-scoped routers: endpoints are relative to the env base URL.

package/build/tools/index.js

@@ -196,7 +196,7 @@ export async function executeTool(api, toolName, args) {
                 };
             }
             catch (error) {
-                throw new Error(`Failed to convert date: ${error instanceof Error ? error.message : String(error)}`);
+                throw new Error(`Failed to convert date: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
             }
         }
         case 'ebay_validate_token_expiry': {
@@ -217,7 +217,7 @@ export async function executeTool(api, toolName, args) {
                 };
             }
             catch (error) {
-                throw new Error(`Failed to validate token expiry: ${error instanceof Error ? error.message : String(error)}`);
+                throw new Error(`Failed to validate token expiry: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
             }
         }
         case 'ebay_set_user_tokens_with_expiry': {
@@ -272,7 +272,7 @@ export async function executeTool(api, toolName, args) {
                 };
             }
             catch (error) {
-                throw new Error(`Failed to set user tokens: ${error instanceof Error ? error.message : String(error)}`);
+                throw new Error(`Failed to set user tokens: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
             }
         }
         case 'ebay_display_credentials': {
@@ -370,7 +370,7 @@ export async function executeTool(api, toolName, args) {
                 };
             }
             catch (error) {
-                throw new Error(`Failed to exchange authorization code: ${error instanceof Error ? error.message : String(error)}`);
+                throw new Error(`Failed to exchange authorization code: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
             }
         }
         case 'ebay_refresh_access_token': {
@@ -401,7 +401,7 @@ export async function executeTool(api, toolName, args) {
                 };
             }
             catch (error) {
-                throw new Error(`Failed to refresh access token: ${error instanceof Error ? error.message : String(error)}`);
+                throw new Error(`Failed to refresh access token: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
             }
         }
         // Account Management

package/build/validation/effective-context.js

@@ -0,0 +1,77 @@
+function sanitizeText(value) {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function buildCompactText(...parts) {
+    const compact = parts
+        .map((part) => sanitizeText(part))
+        .filter((part) => part !== null)
+        .join(' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    return compact.length > 0 ? compact : null;
+}
+function getQueryContext(request) {
+    return request.validation.queryContext;
+}
+function getFallbackArtist(request) {
+    return sanitizeText(request.item.canonicalArtists[0]);
+}
+function getFallbackAlbum(request) {
+    return sanitizeText(request.item.relatedAlbums[0]);
+}
+function getFallbackItem(request) {
+    return sanitizeText(request.item.name);
+}
+export function buildValidationEffectiveContext(request) {
+    const queryContext = getQueryContext(request);
+    const sourceType = request.sourceContext?.sourceType ?? 'item';
+    const searchArtist = sanitizeText(queryContext?.resolvedSearchArtist) ?? getFallbackArtist(request);
+    const searchAlbum = sanitizeText(getFallbackAlbum(request));
+    const searchItem = sanitizeText(queryContext?.resolvedSearchItem) ??
+        (sourceType === 'item' ? getFallbackItem(request) : null);
+    const searchEvent = sanitizeText(queryContext?.resolvedSearchEvent);
+    const searchLocation = sanitizeText(queryContext?.resolvedSearchLocation);
+    const resolvedSearchQuery = sanitizeText(queryContext?.resolvedSearchQuery);
+    const itemRecordId = sanitizeText(request.item.recordId);
+    const eventRecordId = sanitizeText(request.sourceContext?.eventRecordId);
+    const itemName = getFallbackItem(request);
+    const hasItem = sourceType === 'item'
+        ? (request.sourceContext?.hasItem ?? itemRecordId !== null) || itemName !== null
+        : request.sourceContext?.hasItem === true || itemRecordId !== null;
+    const hasEvent = sourceType === 'event'
+        ? true
+        : request.sourceContext?.hasEvent === true || searchEvent !== null || eventRecordId !== null;
+    const effectiveSearchQuery = resolvedSearchQuery ??
+        (sourceType === 'event'
+            ? buildCompactText(searchArtist, searchEvent, searchItem, searchLocation)
+            : buildCompactText(searchArtist, searchAlbum ?? searchItem, searchLocation));
+    return {
+        sourceType,
+        mode: sourceType,
+        validationScope: sanitizeText(queryContext?.validationScope),
+        queryScope: sanitizeText(queryContext?.queryScope),
+        directQueryActive: queryContext?.directQueryActive === true,
+        resolvedSearchQuery,
+        effectiveSearchQuery,
+        searchArtist,
+        searchAlbum,
+        searchItem,
+        searchEvent,
+        searchLocation,
+        hasItem,
+        hasEvent,
+        itemRecordId,
+        eventRecordId,
+        itemName,
+        eventDate: sanitizeText(request.item.releaseDate),
+        dDay: request.validation.dDay,
+        requestTimestamp: request.timestamp,
+    };
+}
+export function getValidationEffectiveContext(request) {
+    return request.effectiveContext ?? buildValidationEffectiveContext(request);
+}

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

@@ -1,4 +1,5 @@
 import axios from 'axios';
+import { buildResolvedSoldQueryPlan } from './query-utils.js';
 function round(value) {
     return Math.round(value * 100) / 100;
 }
@@ -14,23 +15,6 @@ function normalizePrice(value) {
     }
     return null;
 }
-function buildSoldKeywords(request) {
-    const parts = new Set();
-    const push = (values) => {
-        for (const value of values) {
-            const normalized = value.trim();
-            if (normalized) {
-                parts.add(normalized);
-            }
-        }
-    };
-    push([request.item.name]);
-    push(request.item.canonicalArtists.slice(0, 2));
-    push(request.item.relatedAlbums.slice(0, 1));
-    push(request.item.variation.slice(0, 2));
-    push([request.validation.validationType]);
-    return Array.from(parts).join(' ').replace(/\s+/g, ' ').trim();
-}
 function parseSoldDate(value) {
     if (!value) {
         return null;
@@ -96,7 +80,7 @@ function scoreSoldConfidence(soldResultsCount, soldItemsSample) {
     }
     return 'Low';
 }
-function createEmptySoldSignals(query, status, errorMessage) {
+function createEmptySoldSignals(query, queryCandidates = [], status, errorMessage) {
     return {
         provider: 'third_party_sold_api',
         confidence: 'Low',
@@ -115,6 +99,9 @@ function createEmptySoldSignals(query, status, errorMessage) {
             daysTracked: null,
         },
         query,
+        queryCandidates,
+        selectedQuery: query ?? undefined,
+        selectedQueryTier: query ? 1 : null,
         responseUrl: null,
         status,
         ...(errorMessage ? { errorMessage } : {}),
@@ -123,49 +110,107 @@ function createEmptySoldSignals(query, status, 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 query = buildSoldKeywords(request);
+    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, 'unavailable');
+        return {
+            ...createEmptySoldSignals(query, queryCandidates, 'unavailable'),
+            queryDiagnostics,
+            queryResolution,
+        };
     }
     try {
         const endpoint = soldApiUrl.endsWith('/findCompletedItems')
             ? soldApiUrl
             : `${soldApiUrl.replace(/\/$/, '')}/findCompletedItems`;
         const host = new URL(endpoint).host;
-        const response = await axios.post(endpoint, {
-            keywords: query,
-            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;
+        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 {
-            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,
-            responseUrl: typeof data.response_url === 'string' ? data.response_url : null,
-            status: data.success === false ? 'error' : 'ok',
+            ...selectedResult,
+            queryResolution,
         };
     }
     catch (error) {
-        return createEmptySoldSignals(query, 'error', error instanceof Error ? error.message : String(error));
+        return {
+            ...createEmptySoldSignals(query, queryCandidates, 'error', error instanceof Error ? error.message : String(error)),
+            queryDiagnostics,
+            queryResolution,
+        };
     }
 }