ebay-mcp-remote-edition 3.1.2 → 3.3.0

package/build/validation/providers/terapeak.js

@@ -0,0 +1,30 @@
+import { buildResolvedValidationQueryPlan } from './query-utils.js';
+export async function getTerapeakValidationSignals(_api, request) {
+    await Promise.resolve();
+    const { queryPlan, queryResolution } = buildResolvedValidationQueryPlan(request);
+    const queryCandidates = queryPlan.map((candidate) => candidate.query);
+    const currentQuery = queryCandidates[0] ?? null;
+    const previousPobQuery = queryCandidates[1] ?? currentQuery;
+    return {
+        avgWatchersPerListing: null,
+        preOrderListingsCount: null,
+        marketPriceUsd: null,
+        avgShippingCostUsd: null,
+        competitionLevel: null,
+        previousPobAvgPriceUsd: null,
+        previousPobSellThroughPct: null,
+        currentListingsCount: null,
+        soldListingsCount: null,
+        provider: 'none',
+        confidence: 'Low',
+        queryDebug: {
+            currentQuery,
+            previousPobQuery,
+            selectedMode: 'combined',
+            currentResultCount: null,
+            previousPobResultCount: null,
+            queryResolution,
+            notes: 'Terapeak/eBay research provider contract is in place, but live authenticated research retrieval is not implemented yet.',
+        },
+    };
+}

package/build/validation/recommendation.js

@@ -0,0 +1,100 @@
+function addHours(timestamp, hours) {
+    return new Date(new Date(timestamp).getTime() + hours * 60 * 60 * 1000).toISOString();
+}
+export function buildValidationRecommendation(request, signals) {
+    const dDay = request.validation.dDay;
+    const baseCadence = typeof dDay === 'number' && dDay >= -3 && dDay <= 3 ? 'Hourly' : 'Daily';
+    const shouldAutoTrack = request.validation.autoCheckEnabled &&
+        request.validation.automationStatus === 'Watching' &&
+        request.validation.buyDecision === 'Watching';
+    const trackingCadence = shouldAutoTrack ? baseCadence : 'Off';
+    const nextCheckAt = !shouldAutoTrack
+        ? null
+        : trackingCadence === 'Hourly'
+            ? addHours(request.timestamp, 1)
+            : addHours(request.timestamp, 24);
+    const marketPrice = signals.terapeak.marketPriceUsd ??
+        signals.sold.soldMedianPriceUsd ??
+        signals.ebay.marketPriceUsd;
+    const preorderListingsCount = signals.terapeak.preOrderListingsCount ?? signals.ebay.preOrderListingsCount;
+    const wholesale = request.item.wholesalePrice;
+    const marginRatio = marketPrice !== null && wholesale !== null && wholesale > 0
+        ? (marketPrice - wholesale) / wholesale
+        : null;
+    const recentSoldCount = [
+        signals.sold.soldVelocity.day1Sold,
+        signals.sold.soldVelocity.day2Sold,
+        signals.sold.soldVelocity.day3Sold,
+    ].reduce((sum, value) => sum + (value ?? 0), 0);
+    let latestAiRecommendation = 'Continue watching until stronger market signal appears.';
+    let latestAiConfidence = 'Medium';
+    let monitoringNotes = 'Baseline recommendation generated from current validation state.';
+    if (!shouldAutoTrack) {
+        latestAiRecommendation =
+            'Automatic tracking paused because the validation is no longer in a watchable state.';
+        latestAiConfidence = 'High';
+        monitoringNotes =
+            'Stop conditions were met, so automation will not schedule another validation run.';
+    }
+    else if (marginRatio !== null &&
+        marginRatio >= 1 &&
+        preorderListingsCount !== null &&
+        preorderListingsCount >= 25) {
+        latestAiRecommendation =
+            'Demand and pricing look constructive. Continue tracking closely and be ready to upgrade from watch status if sell-through strengthens.';
+        latestAiConfidence = 'High';
+        monitoringNotes =
+            'Healthy active-listing volume and strong projected margin support continued monitoring.';
+        if (signals.sold.soldMedianPriceUsd !== null) {
+            monitoringNotes =
+                'Healthy active-listing volume and sold comparables support continued monitoring without yet forcing a buy-state change.';
+        }
+    }
+    else if (signals.sold.soldMedianPriceUsd !== null &&
+        recentSoldCount > 0 &&
+        signals.sold.confidence !== 'Low') {
+        latestAiRecommendation =
+            'Recent sold comparables support real resale demand. Continue watching closely while waiting for a stronger conviction signal.';
+        latestAiConfidence = signals.sold.confidence === 'High' ? 'High' : 'Medium';
+        monitoringNotes =
+            'Sold-item data confirms recent transaction activity, improving confidence while remaining conservative on buy-state changes.';
+    }
+    else if (signals.sold.soldMedianPriceUsd !== null) {
+        latestAiRecommendation =
+            'Sold comps are available, but sample depth is still limited. Keep monitoring until resale momentum becomes clearer.';
+        latestAiConfidence = 'Medium';
+        monitoringNotes =
+            'Temporary sold-provider data is present, but sample depth is not yet strong enough to justify an automatic buy-decision change.';
+    }
+    else if (signals.social.twitterTrending === true ||
+        (signals.social.youtubeViews24hMillions !== null &&
+            signals.social.youtubeViews24hMillions >= 0.1) ||
+        (signals.social.redditPostsCount7d !== null && signals.social.redditPostsCount7d >= 5)) {
+        latestAiRecommendation =
+            'Demand signals are mixed. Keep monitoring until eBay pricing and social momentum become more decisive.';
+        latestAiConfidence = 'Medium';
+        monitoringNotes =
+            'Cross-channel social activity exists, but it is only being used as a supporting confidence signal and is not strong enough to justify an automatic buy change.';
+    }
+    if (signals.terapeak.previousPobSellThroughPct !== null &&
+        signals.terapeak.previousPobSellThroughPct >= 50) {
+        monitoringNotes +=
+            ' Previous POB sell-through research suggests the comparable release sold through efficiently.';
+        if (latestAiConfidence !== 'High') {
+            latestAiConfidence = 'Medium';
+        }
+    }
+    if (signals.research.previousComebackFirstWeekSales !== null) {
+        monitoringNotes += ` Previous comeback first-week sales reference: ${signals.research.previousComebackFirstWeekSales}.`;
+    }
+    return {
+        buyDecision: request.validation.buyDecision,
+        automationStatus: shouldAutoTrack ? 'Watching' : 'Paused',
+        trackingCadence,
+        shouldAutoTrack,
+        nextCheckAt,
+        latestAiRecommendation,
+        latestAiConfidence,
+        monitoringNotes,
+    };
+}

package/build/validation/run-validation.js

@@ -0,0 +1,374 @@
+import { validationRunRequestSchema } from './schemas.js';
+import { getEbayValidationSignals } from './providers/ebay.js';
+import { getEbaySoldValidationSignals } from './providers/ebay-sold.js';
+import { getTerapeakValidationSignals } from './providers/terapeak.js';
+import { getSocialValidationSignals } from './providers/social.js';
+import { getChartValidationSignals } from './providers/chart.js';
+import { getPreviousComebackResearchSignals } from './providers/research.js';
+import { buildProviderQueryResolutionDebug } from './providers/query-utils.js';
+import { buildValidationRecommendation } from './recommendation.js';
+function addMinutes(timestamp, minutes) {
+    return new Date(new Date(timestamp).getTime() + minutes * 60 * 1000).toISOString();
+}
+function mapErrorCode(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (/refresh|authorization expired|access token|token/i.test(message)) {
+        return 'EBAY_AUTH_FAILED';
+    }
+    return 'VALIDATION_RUN_FAILED';
+}
+function getValidationId(input) {
+    if (typeof input === 'object' &&
+        input !== null &&
+        'validationId' in input &&
+        typeof input.validationId === 'string') {
+        return input.validationId;
+    }
+    return '';
+}
+function isMeaningfulWriteValue(value) {
+    if (value === null || value === undefined) {
+        return false;
+    }
+    return typeof value !== 'string' || value.length > 0;
+}
+function getFieldPresence(fields) {
+    const contributed = [];
+    const omitted = [];
+    for (const [field, value] of Object.entries(fields)) {
+        if (isMeaningfulWriteValue(value)) {
+            contributed.push(field);
+        }
+        else {
+            omitted.push(field);
+        }
+    }
+    return { contributed, omitted };
+}
+function getWriteSource(value, source) {
+    return isMeaningfulWriteValue(value) ? source : 'none';
+}
+function buildProviderDebug(request, ebay, sold, terapeak, social, chart, research) {
+    const requestQueryResolution = buildProviderQueryResolutionDebug(request, Boolean(ebay.queryResolution?.queryContextUsed));
+    const ebayFields = getFieldPresence({
+        avgWatchersPerListing: ebay.avgWatchersPerListing,
+        preOrderListingsCount: ebay.preOrderListingsCount,
+        marketPriceUsd: ebay.marketPriceUsd,
+        avgShippingCostUsd: ebay.avgShippingCostUsd,
+        competitionLevel: ebay.competitionLevel,
+    });
+    const soldFields = getFieldPresence({
+        soldAveragePriceUsd: sold.soldAveragePriceUsd,
+        soldMedianPriceUsd: sold.soldMedianPriceUsd,
+        soldMinPriceUsd: sold.soldMinPriceUsd,
+        soldMaxPriceUsd: sold.soldMaxPriceUsd,
+        day1Sold: sold.soldVelocity.day1Sold,
+        day2Sold: sold.soldVelocity.day2Sold,
+        day3Sold: sold.soldVelocity.day3Sold,
+        day4Sold: sold.soldVelocity.day4Sold,
+        day5Sold: sold.soldVelocity.day5Sold,
+        daysTracked: sold.soldVelocity.daysTracked,
+    });
+    const terapeakFields = getFieldPresence({
+        avgWatchersPerListing: terapeak.avgWatchersPerListing,
+        preOrderListingsCount: terapeak.preOrderListingsCount,
+        marketPriceUsd: terapeak.marketPriceUsd,
+        avgShippingCostUsd: terapeak.avgShippingCostUsd,
+        competitionLevel: terapeak.competitionLevel,
+        previousPobAvgPriceUsd: terapeak.previousPobAvgPriceUsd,
+        previousPobSellThroughPct: terapeak.previousPobSellThroughPct,
+    });
+    const socialFields = getFieldPresence({
+        twitterTrending: social.twitterTrending,
+        youtubeViews24hMillions: social.youtubeViews24hMillions,
+        redditPostsCount7d: social.redditPostsCount7d,
+    });
+    const researchFields = getFieldPresence({
+        previousAlbumTitle: research.previousAlbumTitle,
+        previousComebackFirstWeekSales: research.previousComebackFirstWeekSales,
+    });
+    const ebayStatus = (ebay.queryCandidates?.length ?? 0) === 0
+        ? 'unavailable'
+        : ebay.sampleSize > 0
+            ? 'ok'
+            : 'partial';
+    const socialStatus = socialFields.contributed.length > 0 ? 'ok' : social.debug ? 'partial' : 'unavailable';
+    const terapeakStatus = terapeak.provider === 'none'
+        ? 'stub'
+        : terapeakFields.contributed.length > 0
+            ? 'ok'
+            : 'partial';
+    const researchStatus = research.previousComebackFirstWeekSales !== null || research.previousAlbumTitle !== null
+        ? 'ok'
+        : 'stub';
+    return {
+        ebay: {
+            status: ebayStatus,
+            confidence: ebay.sampleSize >= 10 ? 'medium' : 'low',
+            browseSampleSize: ebay.sampleSize,
+            queryCandidates: ebay.queryCandidates ?? [],
+            selectedQuery: ebay.selectedQuery,
+            selectedQueryTier: ebay.selectedQueryTier,
+            queryDiagnostics: ebay.queryDiagnostics ?? [],
+            queryContextUsed: ebay.queryResolution?.queryContextUsed ?? requestQueryResolution.queryContextUsed,
+            querySource: ebay.queryResolution?.querySource ?? requestQueryResolution.querySource,
+            resolvedSearchQuery: ebay.queryResolution?.resolvedSearchQuery ?? requestQueryResolution.resolvedSearchQuery,
+            validationScope: ebay.queryResolution?.validationScope ?? requestQueryResolution.validationScope,
+            queryScope: ebay.queryResolution?.queryScope ?? requestQueryResolution.queryScope,
+            selectionReason: ebay.selectionReason,
+            errorMessage: ebay.errorMessage,
+            responseStatus: ebay.responseStatus,
+            responseBodyExcerpt: ebay.responseBodyExcerpt,
+            contributedFields: ebayFields.contributed,
+            omittedFields: ebayFields.omitted,
+        },
+        sold: {
+            status: sold.status,
+            provider: sold.provider,
+            confidence: sold.confidence.toLowerCase(),
+            soldResultsCount: sold.soldResultsCount,
+            queryCandidates: sold.queryCandidates ?? [],
+            selectedQuery: sold.selectedQuery,
+            selectedQueryTier: sold.selectedQueryTier,
+            queryContextUsed: sold.queryResolution?.queryContextUsed ?? requestQueryResolution.queryContextUsed,
+            querySource: sold.queryResolution?.querySource ?? requestQueryResolution.querySource,
+            resolvedSearchQuery: sold.queryResolution?.resolvedSearchQuery ?? requestQueryResolution.resolvedSearchQuery,
+            validationScope: sold.queryResolution?.validationScope ?? requestQueryResolution.validationScope,
+            queryScope: sold.queryResolution?.queryScope ?? requestQueryResolution.queryScope,
+            contributedFields: soldFields.contributed,
+            omittedFields: soldFields.omitted,
+            errorMessage: sold.errorMessage,
+        },
+        terapeak: {
+            status: terapeakStatus,
+            provider: terapeak.provider,
+            confidence: terapeak.confidence.toLowerCase(),
+            queryCandidates: [
+                terapeak.queryDebug.currentQuery,
+                terapeak.queryDebug.previousPobQuery,
+            ].filter((value) => typeof value === 'string' && value.length > 0),
+            currentQuery: terapeak.queryDebug.currentQuery,
+            previousPobQuery: terapeak.queryDebug.previousPobQuery,
+            queryContextUsed: terapeak.queryDebug.queryResolution?.queryContextUsed ??
+                requestQueryResolution.queryContextUsed,
+            querySource: terapeak.queryDebug.queryResolution?.querySource ?? requestQueryResolution.querySource,
+            resolvedSearchQuery: terapeak.queryDebug.queryResolution?.resolvedSearchQuery ??
+                requestQueryResolution.resolvedSearchQuery,
+            validationScope: terapeak.queryDebug.queryResolution?.validationScope ??
+                requestQueryResolution.validationScope,
+            queryScope: terapeak.queryDebug.queryResolution?.queryScope ?? requestQueryResolution.queryScope,
+            selectedMode: terapeak.queryDebug.selectedMode,
+            currentResultCount: terapeak.queryDebug.currentResultCount,
+            previousPobResultCount: terapeak.queryDebug.previousPobResultCount,
+            contributedFields: terapeakFields.contributed,
+            omittedFields: terapeakFields.omitted,
+            notes: terapeak.queryDebug.notes,
+        },
+        social: {
+            status: socialStatus,
+            confidence: 'low',
+            queryContextUsed: requestQueryResolution.queryContextUsed,
+            querySource: requestQueryResolution.querySource,
+            resolvedSearchQuery: requestQueryResolution.resolvedSearchQuery,
+            validationScope: requestQueryResolution.validationScope,
+            queryScope: requestQueryResolution.queryScope,
+            contributedFields: socialFields.contributed,
+            omittedFields: socialFields.omitted,
+            details: social.debug,
+        },
+        chart: {
+            status: 'stub',
+            confidence: 'low',
+            contributedFields: [],
+            omittedFields: ['chartMomentum'],
+        },
+        research: {
+            status: researchStatus,
+            confidence: research.confidence.toLowerCase(),
+            previousAlbumTitle: research.previousAlbumTitle,
+            previousComebackFirstWeekSales: research.previousComebackFirstWeekSales,
+            contributedFields: researchFields.contributed,
+            omittedFields: researchFields.omitted,
+            notes: research.notes,
+            sources: research.sources ?? [],
+        },
+    };
+}
+export async function runValidation(api, input) {
+    let request;
+    try {
+        request = validationRunRequestSchema.parse(input);
+    }
+    catch (error) {
+        return {
+            status: 'error',
+            validationId: getValidationId(input),
+            errorCode: 'VALIDATION_REQUEST_INVALID',
+            message: error instanceof Error ? error.message : String(error),
+            retryable: false,
+            nextCheckAt: null,
+        };
+    }
+    try {
+        const ebay = await getEbayValidationSignals(api, request);
+        const sold = await getEbaySoldValidationSignals(request);
+        const terapeak = await getTerapeakValidationSignals(api, request);
+        const social = await getSocialValidationSignals(request);
+        const chart = getChartValidationSignals(request);
+        const research = await getPreviousComebackResearchSignals(request);
+        const mergedAvgWatchers = terapeak.avgWatchersPerListing ?? ebay.avgWatchersPerListing;
+        const mergedPreorderListings = terapeak.preOrderListingsCount ?? ebay.preOrderListingsCount;
+        const marketPriceUsd = terapeak.marketPriceUsd ?? sold.soldMedianPriceUsd ?? ebay.marketPriceUsd;
+        const mergedAvgShippingCostUsd = terapeak.avgShippingCostUsd ?? ebay.avgShippingCostUsd;
+        const mergedCompetitionLevel = terapeak.competitionLevel ?? ebay.competitionLevel;
+        const soldVelocity = {
+            day1Sold: sold.soldVelocity.day1Sold ?? ebay.soldVelocity.day1Sold,
+            day2Sold: sold.soldVelocity.day2Sold ?? ebay.soldVelocity.day2Sold,
+            day3Sold: sold.soldVelocity.day3Sold ?? ebay.soldVelocity.day3Sold,
+            day4Sold: sold.soldVelocity.day4Sold ?? ebay.soldVelocity.day4Sold,
+            day5Sold: sold.soldVelocity.day5Sold ?? ebay.soldVelocity.day5Sold,
+            daysTracked: sold.soldVelocity.daysTracked ?? ebay.soldVelocity.daysTracked,
+        };
+        const recommendation = buildValidationRecommendation(request, {
+            ebay,
+            sold,
+            terapeak,
+            social,
+            chart,
+            research,
+        });
+        const requestQueryResolution = buildProviderQueryResolutionDebug(request, Boolean(ebay.queryResolution?.queryContextUsed));
+        const mergedSignals = { ebay, sold, terapeak, social, chart, research };
+        const socialWrites = {
+            ...(social.twitterTrending !== null ? { twitterTrending: social.twitterTrending } : {}),
+            ...(social.youtubeViews24hMillions !== null
+                ? { youtubeViews24hMillions: social.youtubeViews24hMillions }
+                : {}),
+            ...(social.redditPostsCount7d !== null
+                ? { redditPostsCount7d: social.redditPostsCount7d }
+                : {}),
+        };
+        const terapeakWrites = {
+            ...(terapeak.previousPobAvgPriceUsd !== null
+                ? { previousPobAvgPriceUsd: terapeak.previousPobAvgPriceUsd }
+                : {}),
+            ...(terapeak.previousPobSellThroughPct !== null
+                ? { previousPobSellThroughPct: terapeak.previousPobSellThroughPct }
+                : {}),
+        };
+        const researchWrites = {
+            ...(research.previousComebackFirstWeekSales !== null
+                ? { previousComebackFirstWeekSales: research.previousComebackFirstWeekSales }
+                : {}),
+        };
+        const writeResolution = {
+            avgWatchersPerListing: terapeak.avgWatchersPerListing !== null
+                ? 'terapeak'
+                : getWriteSource(ebay.avgWatchersPerListing, 'ebay'),
+            preOrderListingsCount: terapeak.preOrderListingsCount !== null
+                ? 'terapeak'
+                : getWriteSource(ebay.preOrderListingsCount, 'ebay'),
+            marketPriceUsd: terapeak.marketPriceUsd !== null
+                ? 'terapeak'
+                : sold.soldMedianPriceUsd !== null
+                    ? 'sold'
+                    : getWriteSource(ebay.marketPriceUsd, 'ebay'),
+            avgShippingCostUsd: terapeak.avgShippingCostUsd !== null
+                ? 'terapeak'
+                : getWriteSource(ebay.avgShippingCostUsd, 'ebay'),
+            competitionLevel: terapeak.competitionLevel !== null
+                ? 'terapeak'
+                : getWriteSource(ebay.competitionLevel, 'ebay'),
+            twitterTrending: getWriteSource(social.twitterTrending, 'social'),
+            youtubeViews24hMillions: getWriteSource(social.youtubeViews24hMillions, 'social'),
+            redditPostsCount7d: getWriteSource(social.redditPostsCount7d, 'social'),
+            day1Sold: sold.soldVelocity.day1Sold !== null
+                ? 'sold'
+                : getWriteSource(ebay.soldVelocity.day1Sold, 'ebay'),
+            day2Sold: sold.soldVelocity.day2Sold !== null
+                ? 'sold'
+                : getWriteSource(ebay.soldVelocity.day2Sold, 'ebay'),
+            day3Sold: sold.soldVelocity.day3Sold !== null
+                ? 'sold'
+                : getWriteSource(ebay.soldVelocity.day3Sold, 'ebay'),
+            day4Sold: sold.soldVelocity.day4Sold !== null
+                ? 'sold'
+                : getWriteSource(ebay.soldVelocity.day4Sold, 'ebay'),
+            day5Sold: sold.soldVelocity.day5Sold !== null
+                ? 'sold'
+                : getWriteSource(ebay.soldVelocity.day5Sold, 'ebay'),
+            daysTracked: sold.soldVelocity.daysTracked !== null
+                ? 'sold'
+                : getWriteSource(ebay.soldVelocity.daysTracked, 'ebay'),
+            previousPobAvgPriceUsd: getWriteSource(terapeak.previousPobAvgPriceUsd, 'terapeak'),
+            previousPobSellThroughPct: getWriteSource(terapeak.previousPobSellThroughPct, 'terapeak'),
+            previousComebackFirstWeekSales: getWriteSource(research.previousComebackFirstWeekSales, 'research'),
+        };
+        const omittedOptionalWrites = Object.entries(writeResolution)
+            .filter(([, source]) => source === 'none')
+            .map(([field]) => field);
+        return {
+            status: 'ok',
+            validationId: request.validationId,
+            writes: {
+                avgWatchersPerListing: mergedAvgWatchers,
+                preOrderListingsCount: mergedPreorderListings,
+                ...socialWrites,
+                marketPriceUsd,
+                avgShippingCostUsd: mergedAvgShippingCostUsd,
+                competitionLevel: mergedCompetitionLevel,
+                marketPriceTrend: ebay.marketPriceTrend,
+                day1Sold: soldVelocity.day1Sold,
+                day2Sold: soldVelocity.day2Sold,
+                day3Sold: soldVelocity.day3Sold,
+                day4Sold: soldVelocity.day4Sold,
+                day5Sold: soldVelocity.day5Sold,
+                daysTracked: soldVelocity.daysTracked,
+                ...terapeakWrites,
+                ...researchWrites,
+                monitoringNotes: recommendation.monitoringNotes,
+                lastDataSnapshot: JSON.stringify(mergedSignals),
+                latestAiRecommendation: recommendation.latestAiRecommendation,
+                latestAiConfidence: recommendation.latestAiConfidence,
+                validationError: '',
+            },
+            decision: {
+                buyDecision: recommendation.buyDecision,
+                automationStatus: recommendation.automationStatus,
+                trackingCadence: recommendation.trackingCadence,
+                shouldAutoTrack: recommendation.shouldAutoTrack,
+                nextCheckAt: recommendation.nextCheckAt,
+            },
+            debug: {
+                ebayQuery: ebay.ebayQuery,
+                soldQuery: sold.query,
+                queryCandidates: {
+                    ebay: ebay.queryCandidates ?? [],
+                    sold: sold.queryCandidates ?? [],
+                    terapeak: [terapeak.queryDebug.currentQuery, terapeak.queryDebug.previousPobQuery].filter((value) => typeof value === 'string' && value.length > 0),
+                },
+                browseSampleSize: ebay.sampleSize,
+                soldResultsCount: sold.soldResultsCount,
+                omittedOptionalWrites,
+                writeResolution,
+                sourceSet: ['ebay', 'sold', 'terapeak', 'social', 'chart', 'research'],
+                providers: buildProviderDebug(request, ebay, sold, terapeak, social, chart, research),
+                queryContextUsed: requestQueryResolution.queryContextUsed,
+                querySource: requestQueryResolution.querySource,
+                resolvedSearchQuery: requestQueryResolution.resolvedSearchQuery,
+                validationScope: requestQueryResolution.validationScope,
+                queryScope: requestQueryResolution.queryScope,
+            },
+        };
+    }
+    catch (error) {
+        return {
+            status: 'error',
+            validationId: request.validationId,
+            errorCode: mapErrorCode(error),
+            message: error instanceof Error ? error.message : String(error),
+            retryable: true,
+            nextCheckAt: addMinutes(request.timestamp, 30),
+        };
+    }
+}

package/build/validation/schemas.js

@@ -0,0 +1,105 @@
+import { z } from 'zod';
+export const trackingCadenceSchema = z.enum(['Daily', 'Hourly', 'Off']);
+export const validationCurrentMetricsSchema = z.object({
+    avgWatchersPerListing: z.number().nullable(),
+    preOrderListingsCount: z.number().nullable(),
+    twitterTrending: z.boolean(),
+    youtubeViews24hMillions: z.number().nullable(),
+    redditPostsCount7d: z.number().nullable(),
+    marketPriceUsd: z.number().nullable(),
+    avgShippingCostUsd: z.number().nullable(),
+    competitionLevel: z.number().nullable(),
+    marketPriceTrend: z.string(),
+    day1Sold: z.number().nullable(),
+    day2Sold: z.number().nullable(),
+    day3Sold: z.number().nullable(),
+    day4Sold: z.number().nullable(),
+    day5Sold: z.number().nullable(),
+    daysTracked: z.number().nullable(),
+});
+export const validationQueryContextSchema = z.object({
+    resolvedSearchQuery: z.string().nullable().optional(),
+    validationScope: z.string().nullable().optional(),
+    queryScope: z.string().nullable().optional(),
+});
+export const validationRunRequestSchema = z.object({
+    validationId: z.string().min(1),
+    runType: z.enum(['scheduled', 'manual']),
+    cadence: trackingCadenceSchema,
+    timestamp: z.string().datetime({ offset: true }),
+    item: z.object({
+        recordId: z.string().min(1),
+        name: z.string().min(1),
+        variation: z.array(z.string()),
+        itemType: z.array(z.string()),
+        releaseType: z.array(z.string()),
+        releaseDate: z.string().datetime({ offset: true }).nullable(),
+        releasePeriod: z.array(z.string()),
+        availability: z.array(z.string()),
+        wholesalePrice: z.number().nullable(),
+        supplierNames: z.array(z.string()),
+        canonicalArtists: z.array(z.string()),
+        relatedAlbums: z.array(z.string()),
+    }),
+    validation: z.object({
+        validationType: z.string(),
+        buyDecision: z.string(),
+        automationStatus: z.string(),
+        autoCheckEnabled: z.boolean(),
+        dDay: z.number().nullable(),
+        artistTier: z.string(),
+        initialBudget: z.number().nullable(),
+        reserveBudget: z.number().nullable(),
+        queryContext: validationQueryContextSchema.optional(),
+        currentMetrics: validationCurrentMetricsSchema,
+    }),
+});
+export const validationWritesSchema = z.object({
+    avgWatchersPerListing: z.number().nullable().optional(),
+    preOrderListingsCount: z.number().nullable().optional(),
+    twitterTrending: z.boolean().optional(),
+    youtubeViews24hMillions: z.number().nullable().optional(),
+    redditPostsCount7d: z.number().nullable().optional(),
+    marketPriceUsd: z.number().nullable().optional(),
+    avgShippingCostUsd: z.number().nullable().optional(),
+    competitionLevel: z.number().nullable().optional(),
+    marketPriceTrend: z.string().optional(),
+    day1Sold: z.number().nullable().optional(),
+    day2Sold: z.number().nullable().optional(),
+    day3Sold: z.number().nullable().optional(),
+    day4Sold: z.number().nullable().optional(),
+    day5Sold: z.number().nullable().optional(),
+    daysTracked: z.number().nullable().optional(),
+    previousPobAvgPriceUsd: z.number().nullable().optional(),
+    previousPobSellThroughPct: z.number().nullable().optional(),
+    previousComebackFirstWeekSales: z.number().nullable().optional(),
+    monitoringNotes: z.string().optional(),
+    lastDataSnapshot: z.string().optional(),
+    latestAiRecommendation: z.string().optional(),
+    latestAiConfidence: z.enum(['High', 'Medium', 'Low']).optional(),
+    validationError: z.string().optional(),
+});
+export const validationDecisionSchema = z.object({
+    buyDecision: z.string().optional(),
+    automationStatus: z.string().optional(),
+    trackingCadence: trackingCadenceSchema.optional(),
+    shouldAutoTrack: z.boolean().optional(),
+    nextCheckAt: z.string().datetime({ offset: true }).nullable().optional(),
+});
+export const validationRunResponseSchema = z.discriminatedUnion('status', [
+    z.object({
+        status: z.literal('ok'),
+        validationId: z.string(),
+        writes: validationWritesSchema.optional(),
+        decision: validationDecisionSchema.optional(),
+        debug: z.record(z.string(), z.unknown()).optional(),
+    }),
+    z.object({
+        status: z.literal('error'),
+        validationId: z.string(),
+        errorCode: z.string(),
+        message: z.string(),
+        retryable: z.boolean().optional(),
+        nextCheckAt: z.string().datetime({ offset: true }).nullable().optional(),
+    }),
+]);

package/build/validation/types.js

@@ -0,0 +1 @@
+export {};