ebay-mcp-remote-edition 4.2.0 → 4.2.1

package/build/api/client-trading.js

@@ -42,14 +42,234 @@ export class TradingApiClient {
     getBaseUrl() {
         return this.baseUrl;
     }
+    /**
+     * Transform a Trading API item object into a structure that fast-xml-parser
+     * can serialize into valid eBay Trading API XML.
+     *
+     * Handles nested objects like PrimaryCategory, ShippingDetails, ReturnPolicy,
+     * PicturesDetails, and ItemSpecifics that require special XML structure.
+     */
+    transformItemForXML(item) {
+        const transformed = {};
+        for (const [key, value] of Object.entries(item)) {
+            if (value === undefined || value === null)
+                continue;
+            switch (key) {
+                case 'PrimaryCategory':
+                    if (typeof value === 'object') {
+                        transformed[key] = { CategoryID: value.CategoryID };
+                    }
+                    else {
+                        transformed[key] = value;
+                    }
+                    break;
+                case 'StartPrice':
+                    transformed[key] = this.transformPrice(value);
+                    break;
+                case 'Currency':
+                    transformed[key] = value;
+                    break;
+                case 'ListingDuration': {
+                    // Normalize listing duration - map invalid/common values to valid ones
+                    const duration = value;
+                    if (duration === 'GMS' || duration === 'GN') {
+                        // GMS (Good Month) and GN (Good 'til Cancelled) may not be available
+                        transformed[key] = 'Days_30';
+                    }
+                    else {
+                        transformed[key] = value;
+                    }
+                    break;
+                }
+                case 'ShippingDetails':
+                    transformed[key] = this.transformShippingDetails(value);
+                    break;
+                case 'ReturnPolicy':
+                    transformed[key] = this.transformReturnPolicy(value);
+                    break;
+                case 'PicturesDetails':
+                    transformed[key] = this.transformPicturesDetails(value);
+                    break;
+                case 'ItemSpecifics':
+                    transformed[key] = this.transformItemSpecifics(value);
+                    break;
+                case 'PaymentMethods':
+                    // Ensure array of strings becomes array of PaymentMethod elements
+                    if (Array.isArray(value)) {
+                        transformed[key] = value;
+                    }
+                    else {
+                        transformed[key] = value;
+                    }
+                    break;
+                default:
+                    transformed[key] = value;
+                    break;
+            }
+        }
+        // Ensure Currency is always present - extract from StartPrice if not provided
+        if (!transformed.Currency && item.StartPrice) {
+            const sp = item.StartPrice;
+            if (typeof sp === 'object' && sp.currencyID) {
+                transformed.Currency = sp.currencyID;
+            }
+            else {
+                transformed.Currency = 'USD';
+            }
+        }
+        return transformed;
+    }
+    /**
+     * Transform price fields that may have currency attributes.
+     * eBay Trading API expects: <StartPrice currencyID="USD">34.99</StartPrice>
+     */
+    transformPrice(price) {
+        if (typeof price === 'string') {
+            return price;
+        }
+        // Use fast-xml-parser attribute convention: @_<attrName> for attributes, #text for content
+        return {
+            '#text': String(price.value),
+            ...(price.currencyID && { '@_currencyID': price.currencyID }),
+        };
+    }
+    /**
+     * Transform ShippingDetails into proper nested XML structure.
+     */
+    transformShippingDetails(sd) {
+        const transformed = {};
+        if (sd.HandlingTime !== undefined) {
+            transformed.HandlingTime = sd.HandlingTime;
+        }
+        if (sd.ShippingServiceOptions) {
+            const options = sd.ShippingServiceOptions;
+            const serviceOption = {};
+            if (options.ShippingServicePriority) {
+                serviceOption.ShippingServicePriority = options.ShippingServicePriority;
+            }
+            if (options.ShippingServiceID) {
+                serviceOption.ShippingServiceID = options.ShippingServiceID;
+            }
+            if (options.ShippingServiceCost) {
+                serviceOption.ShippingServiceCost = this.transformPrice(options.ShippingServiceCost);
+            }
+            if (options.ShippingType) {
+                serviceOption.ShippingType = options.ShippingType;
+            }
+            transformed.ShippingServiceOptions = serviceOption;
+        }
+        if (sd.InternationalShippingServiceOption) {
+            const intlOptions = sd.InternationalShippingServiceOption;
+            transformed.InternationalShippingServiceOption = intlOptions.map((option) => {
+                const transformedOption = {};
+                if (option.ShippingServicePriority) {
+                    transformedOption.ShippingServicePriority = option.ShippingServicePriority;
+                }
+                if (option.ShippingServiceID) {
+                    transformedOption.ShippingServiceID = option.ShippingServiceID;
+                }
+                if (option.ShippingServiceCost) {
+                    transformedOption.ShippingServiceCost = this.transformPrice(option.ShippingServiceCost);
+                }
+                if (option.ShippingType) {
+                    transformedOption.ShippingType = option.ShippingType;
+                }
+                if (option.Country) {
+                    transformedOption.Country = Array.isArray(option.Country)
+                        ? option.Country
+                        : [option.Country];
+                }
+                return transformedOption;
+            });
+        }
+        return transformed;
+    }
+    /**
+     * Transform ReturnPolicy into proper nested XML structure.
+     * Maps user-friendly values to eBay Trading API enum values.
+     */
+    transformReturnPolicy(rp) {
+        const transformed = {};
+        if (rp.ReturnsAcceptedOption !== undefined) {
+            const val = rp.ReturnsAcceptedOption;
+            // Map user-friendly values to eBay enum values
+            if (val.toLowerCase() === 'yes') {
+                transformed.ReturnsAcceptedOption = 'ReturnsAccepted';
+            }
+            else if (val.toLowerCase() === 'no') {
+                transformed.ReturnsAcceptedOption = 'ReturnsNotAccepted';
+            }
+            else {
+                transformed.ReturnsAcceptedOption = val;
+            }
+        }
+        if (rp.ReturnsWithinOption !== undefined) {
+            const val = rp.ReturnsWithinOption;
+            // Map user-friendly values to eBay enum values (Days30 → Days_30)
+            transformed.ReturnsWithinOption = val.replace(/^Days(\d+)$/, 'Days_$1');
+        }
+        if (rp.Description !== undefined) {
+            transformed.Description = rp.Description;
+        }
+        if (rp.RefundOption !== undefined) {
+            transformed.RefundOption = rp.RefundOption;
+        }
+        return transformed;
+    }
+    /**
+     * Transform PicturesDetails into proper nested XML structure.
+     */
+    transformPicturesDetails(pd) {
+        const transformed = {};
+        if (pd.GalleryType) {
+            transformed.GalleryType = pd.GalleryType;
+        }
+        if (pd.PictureURL) {
+            const urls = pd.PictureURL;
+            transformed.PictureURL = Array.isArray(urls) ? urls : [urls];
+        }
+        return transformed;
+    }
+    /**
+     * Transform ItemSpecifics into proper NameValueList XML structure.
+     * eBay expects:
+     * <ItemSpecifics>
+     *   <NameValueList><Name>Brand</Name><Value>Nike</Value></NameValueList>
+     * </ItemSpecifics>
+     */
+    transformItemSpecifics(specifics) {
+        if (!Array.isArray(specifics))
+            return specifics;
+        // eBay expects: <ItemSpecifics><NameValueList><Name>...</Name><Value>...</Value></NameValueList>...</ItemSpecifics>
+        // fast-xml-parser XMLBuilder: when ItemSpecifics is in isArray list, it creates one <ItemSpecifics> per array item.
+        // So we wrap each spec in { NameValueList: { Name, Value } } and return as a single object.
+        // The caller (transformItemForXML) sets transformed['ItemSpecifics'] = this result.
+        // To get a single <ItemSpecifics> with multiple <NameValueList>, we need to NOT return an array
+        // but instead return the NameValueList array directly, and let the XMLBuilder handle it.
+        // Actually: the cleanest approach is to return the array of NameValueList objects,
+        // and since transformItemForXML assigns it to transformed['ItemSpecifics'], and
+        // ItemSpecifics IS in the isArray list, XMLBuilder will emit multiple <ItemSpecifics>.
+        // FIX: Return a single object with NameValueList array inside.
+        return {
+            NameValueList: specifics.map((spec) => ({
+                Name: spec.name,
+                Value: Array.isArray(spec.value) ? spec.value : [spec.value],
+            })),
+        };
+    }
     async execute(callName, params) {
         const token = await this.restClient.getOAuthClient().getAccessToken();
         const requestTag = `${callName}Request`;
         const responseTag = `${callName}Response`;
+        // Transform Item field for proper XML serialization
+        const transformedParams = { ...params };
+        if (transformedParams.Item && typeof transformedParams.Item === 'object') {
+            transformedParams.Item = this.transformItemForXML(transformedParams.Item);
+        }
         const xmlObj = {};
         xmlObj[requestTag] = {
             '@_xmlns': 'urn:ebay:apis:eBLBaseComponents',
-            ...params,
+            ...transformedParams,
         };
         const xmlBody = `<?xml version="1.0" encoding="utf-8"?>\n${this.builder.build(xmlObj)}`;
         apiLogger.debug(`Trading API ${callName}`, { xmlBody });

package/build/server-http.js

@@ -31,6 +31,27 @@ console.log(`[auth-store] Active KV backend: ${authStore.backendName}`);
 function getServerBaseUrl() {
     return CONFIG.publicBaseUrl || `http://localhost:${CONFIG.port}`;
 }
+function getExpectedOAuthCallbackUrl(serverUrl = getServerBaseUrl()) {
+    return `${serverUrl.replace(/\/+$/, '')}/oauth/callback`;
+}
+function isLocalDevelopmentBaseUrl(baseUrl) {
+    if (!baseUrl) {
+        return false;
+    }
+    try {
+        const { hostname } = new URL(baseUrl);
+        const normalizedHost = hostname.toLowerCase();
+        return (normalizedHost === 'localhost' ||
+            normalizedHost === '127.0.0.1' ||
+            normalizedHost === '::1' ||
+            normalizedHost === 'ebay-local.test' ||
+            normalizedHost.endsWith('.localhost') ||
+            normalizedHost.endsWith('.test'));
+    }
+    catch {
+        return false;
+    }
+}
 function htmlEscape(value) {
     return value
         .replace(/&/g, '&')
@@ -749,6 +770,8 @@ function mountEnvRouter(hardcodedEnv, serverUrl, iconBaseUrl) {
             serverLogger.info(`[${prefix || 'root'}/authorize] Redirecting to eBay OAuth`, {
                 state: stateRecord.state,
                 environment,
+                ruName: ebayConfig.redirectUri,
+                expectedCallbackUrl: getExpectedOAuthCallbackUrl(serverUrl),
             });
             res.redirect(oauthUrl);
         }
@@ -848,6 +871,13 @@ function mountEnvRouter(hardcodedEnv, serverUrl, iconBaseUrl) {
             }
             const stateRecord = await authStore.createOAuthState(environment, returnTo);
             const oauthUrl = getOAuthAuthorizationUrl(ebayConfig.clientId, ebayConfig.redirectUri, environment, getHostedOauthScopes(environment), undefined, stateRecord.state);
+            serverLogger.info(`[${prefix || 'root'}/oauth/start] Redirecting to eBay OAuth`, {
+                state: stateRecord.state,
+                environment,
+                ruName: ebayConfig.redirectUri,
+                expectedCallbackUrl: getExpectedOAuthCallbackUrl(serverUrl),
+                returnTo,
+            });
             res.redirect(oauthUrl);
         }
         catch (error) {
@@ -1066,6 +1096,8 @@ async function handleOAuthCallback(req, res, serverUrl) {
             hasCode: !!code,
             hasState: !!state,
             oauthError,
+            expectedCallbackUrl: getExpectedOAuthCallbackUrl(serverUrl),
+            actualCallbackUrl: `${serverUrl}${req.originalUrl}`,
         });
         if (oauthError) {
             res
@@ -1256,11 +1288,29 @@ async function main() {
         const app = createApp();
         const certPath = process.env.EBAY_LOCAL_TLS_CERT_PATH;
         const keyPath = process.env.EBAY_LOCAL_TLS_KEY_PATH;
-        const useHttps = CONFIG.publicBaseUrl.startsWith('https://') && !!certPath && !!keyPath;
+        const localTlsEligible = isLocalDevelopmentBaseUrl(CONFIG.publicBaseUrl);
+        const useHttps = CONFIG.publicBaseUrl.startsWith('https://') && localTlsEligible && !!certPath && !!keyPath;
         const serverUrl = getServerBaseUrl();
+        serverLogger.info('[startup] Public OAuth URL diagnostics', {
+            publicBaseUrl: CONFIG.publicBaseUrl || '(unset)',
+            serverUrl,
+            expectedCallbackUrl: getExpectedOAuthCallbackUrl(serverUrl),
+            localTlsEligible,
+            hasLocalTlsCertPath: !!certPath,
+            hasLocalTlsKeyPath: !!keyPath,
+            useHttps,
+        });
+        if (CONFIG.publicBaseUrl.startsWith('https://') && !localTlsEligible && (certPath || keyPath)) {
+            serverLogger.warn('[startup] Ignoring local TLS certificate settings for hosted base URL', {
+                publicBaseUrl: CONFIG.publicBaseUrl,
+                hasLocalTlsCertPath: !!certPath,
+                hasLocalTlsKeyPath: !!keyPath,
+            });
+        }
         const onListening = () => {
             const protocol = useHttps ? 'HTTPS' : 'HTTP';
             console.log(`Server running at ${serverUrl} [${protocol}]`);
+            console.log(`OAuth callback:  ${getExpectedOAuthCallbackUrl(serverUrl)}`);
             console.log(`MCP (default):    ${serverUrl}/mcp`);
             console.log(`MCP (sandbox):    ${serverUrl}/sandbox/mcp`);
             console.log(`MCP (production): ${serverUrl}/production/mcp`);

package/build/tools/definitions/trading.js

@@ -1,4 +1,88 @@
 import { z } from 'zod';
+// Schema for Trading API price fields that include currency
+const PriceWithCurrencySchema = z.union([
+    z.string(),
+    z.object({
+        value: z.string().or(z.number()).describe('Price value'),
+        currencyID: z.string().optional().describe('Currency code, e.g., USD, EUR, GBP'),
+    }),
+]);
+// Schema for Trading API item specifics (NameValueList)
+const ItemSpecificsSchema = z.array(z.object({
+    name: z.string().describe('Specific name, e.g., Brand, Colour, Size'),
+    value: z.union([z.string(), z.array(z.string())]).describe('Specific value(s)'),
+}));
+// Schema for Trading API item object
+const TradingItemSchema = z.object({
+    // Required fields
+    Title: z.string().describe('Item title (max 80 characters)'),
+    PrimaryCategory: z
+        .object({
+        CategoryID: z.string().describe('eBay category ID, e.g., "15032"'),
+    })
+        .describe('Primary category for the listing'),
+    StartPrice: PriceWithCurrencySchema.describe('Starting price or fixed price'),
+    ConditionID: z.union([z.number(), z.string()]).describe('eBay condition ID, e.g., 1000 for New'),
+    Country: z.string().describe('ISO country code, e.g., US, GB, DE'),
+    Currency: z.string().optional().describe('Currency code, e.g., USD, EUR, GBP'),
+    DispatchTimeMax: z.union([z.number(), z.string()]).describe('Max dispatch time in days'),
+    ListingDuration: z
+        .string()
+        .describe('Listing duration — use Days_30 (recommended), Days_7, Days_10, Days_14, Days_21, Days_30, Days_60, Days_90. GMS/GN may not be available for all accounts.'),
+    ListingType: z.literal('FixedPriceItem').describe('Must be "FixedPriceItem"'),
+    Quantity: z.union([z.number(), z.string()]).describe('Number of items available'),
+    SKU: z.string().describe('Stock keeping unit / inventory identifier'),
+    // Optional fields
+    Subtitle: z.string().optional().describe('Item subtitle (max 35 characters)'),
+    Description: z.string().optional().describe('HTML description of the item'),
+    ItemSpecifics: ItemSpecificsSchema.optional().describe('Product specifics/attributes'),
+    PicturesDetails: z
+        .object({
+        GalleryType: z.string().optional().describe('Gallery type, e.g., Plus, Summary'),
+        PictureURL: z.array(z.string()).describe('Array of image URLs'),
+    })
+        .optional()
+        .describe('Picture details for the listing'),
+    ShippingDetails: z
+        .object({
+        ShippingServiceOptions: z
+            .object({
+            ShippingServicePriority: z.string().optional().describe('Shipping priority (1-9)'),
+            ShippingServiceID: z.string().describe('eBay shipping service ID'),
+            ShippingServiceCost: PriceWithCurrencySchema.describe('Shipping cost'),
+            ShippingType: z.string().describe('Shipping type: Flat, FlatPlusHandling, or Calculated'),
+        })
+            .describe('Domestic shipping service options'),
+        InternationalShippingServiceOption: z
+            .array(z.object({
+            ShippingServicePriority: z.string().optional().describe('Shipping priority (1-9)'),
+            ShippingServiceID: z.string().describe('eBay shipping service ID'),
+            ShippingServiceCost: PriceWithCurrencySchema.describe('Shipping cost'),
+            ShippingType: z.string().describe('Shipping type'),
+            Country: z.array(z.string()).describe('Array of destination country codes'),
+        }))
+            .optional()
+            .describe('International shipping service options'),
+        HandlingTime: z.union([z.number(), z.string()]).optional().describe('Handling time in days'),
+    })
+        .optional()
+        .describe('Shipping details for the listing'),
+    ReturnPolicy: z
+        .object({
+        ReturnsAcceptedOption: z
+            .string()
+            .describe('Returns accepted: ReturnsAccepted or ReturnsNotAccepted'),
+        ReturnsWithinOption: z
+            .string()
+            .describe('Return window: Days_30, Days_60, Days_90 (with underscore)'),
+        Description: z.string().describe('Return policy description'),
+        RefundOption: z.string().optional().describe('Refund type: MoneyBack or Replacement'),
+    })
+        .optional()
+        .describe('Return policy for the listing'),
+    PaymentMethods: z.array(z.string()).optional().describe('Accepted payment methods'),
+    ProxyItem: z.boolean().optional().describe('Whether this is a proxy item'),
+});
 export const tradingTools = [
     {
         name: 'ebay_get_active_listings',
@@ -19,11 +103,9 @@ export const tradingTools = [
     },
     {
         name: 'ebay_create_listing',
-        description: 'Create a new fixed-price listing.\n\nUses the Trading API (AddFixedPriceItem). Requires complete item details.\n\nRequired: User OAuth token.',
+        description: 'Create a new fixed-price listing.\\n\\nUses the Trading API (AddFixedPriceItem). Requires complete item details.\\n\\nIMPORTANT: Photos are REQUIRED and MUST be hosted on eBay servers. External URLs (even HTTPS) are rejected. To get eBay-hosted photo URLs:\\n1. Upload photos via eBay Seller Hub UI\\n2. Use the eBay Image Hosting API (if enabled for your app)\\n3. Reference existing eBay-hosted URLs from previous listings\\n\\nRequired: User OAuth token.',
         inputSchema: {
-            item: z
-                .record(z.string(), z.unknown())
-                .describe('Item details object. Required fields: Title, PrimaryCategory.CategoryID, StartPrice, ConditionID, Country, Currency, DispatchTimeMax, ListingDuration, ListingType ("FixedPriceItem"), Quantity, SKU.'),
+            item: TradingItemSchema.describe('Trading API item object with eBay-specific field structure.'),
         },
         annotations: { readOnlyHint: false },
     },

package/build/validation/recommendation.js

@@ -1,3 +1,4 @@
+import { computeWeightedValidationScore, shouldApplyAgeAwareCalibration, } from './threshold-calibration.js';
 function addHours(timestamp, hours) {
     return new Date(new Date(timestamp).getTime() + hours * 60 * 60 * 1000).toISOString();
 }
@@ -105,6 +106,14 @@ export function buildValidationRecommendation(request, signals) {
         : signals.research.previousAlbumTitle !== null ||
             signals.research.previousComebackFirstWeekSales !== null ||
             signals.research.perplexityHistoricalContextScore > 0;
+    // ── Age-aware weighted scoring (threshold calibration) ─────────────────
+    // Computes a weighted composite score that adjusts momentum/velocity emphasis
+    // based on how many days the item has been tracked. New items (< 7 days)
+    // get 70% momentum weight (since velocity data is sparse), while established
+    // items get 70% velocity weight (since sales history is reliable).
+    const weightedScore = shouldApplyAgeAwareCalibration(request)
+        ? computeWeightedValidationScore(request, signals.momentumScore)
+        : null;
     let latestAiRecommendation = 'Continue watching until stronger market signal appears.';
     let latestAiConfidence = 'Medium';
     let monitoringNotes = `Baseline recommendation generated from current ${signals.effectiveContext.mode} validation state for ${subjectLabel}.`;
@@ -172,6 +181,16 @@ export function buildValidationRecommendation(request, signals) {
     if (hasUsableHistoricalResearch && signals.research.historicalContextNotes.length > 0) {
         monitoringNotes += ` Historical context (${signals.research.confidence}, score ${signals.research.perplexityHistoricalContextScore}/20): ${signals.research.historicalContextNotes}`;
     }
+    // Append weighted scoring summary to monitoring notes if available
+    if (weightedScore) {
+        monitoringNotes +=
+            `\nAge-weighted score: ${weightedScore.compositeScore}/100 (${weightedScore.classification}). ` +
+                `Item type: ${weightedScore.isNewItem ? 'new (<7 days)' : 'established (>=7 days)'}. ` +
+                `Weights: momentum ${Math.round(weightedScore.weights.momentum * 100)}%, ` +
+                `velocity ${Math.round(weightedScore.weights.velocity * 100)}%. ` +
+                `Effective thresholds — momentum BUY/Watch: ${weightedScore.effectiveThresholds.momentumBuy}/${weightedScore.effectiveThresholds.momentumWatch}, ` +
+                `velocity BUY/Watch: ${weightedScore.effectiveThresholds.velocityBuy}/${weightedScore.effectiveThresholds.velocityWatch}.`;
+    }
     return {
         buyDecision: request.validation.buyDecision,
         automationStatus: shouldAutoTrack ? 'Watching' : 'Paused',
@@ -181,5 +200,7 @@ export function buildValidationRecommendation(request, signals) {
         latestAiRecommendation,
         latestAiConfidence,
         monitoringNotes,
+        // Weighted scoring metadata (used by downstream Airtable formulas)
+        weightedValidationScore: weightedScore ?? undefined,
     };
 }

package/build/validation/run-validation.js

@@ -429,6 +429,8 @@ export async function runValidation(api, input) {
             chart,
             research,
             effectiveContext,
+            // Artist momentum score from Artist/Group table — passed via currentMetrics
+            momentumScore: effectiveRequest.validation.currentMetrics.artistMomentumScore ?? null,
         });
         const requestQueryResolution = buildProviderQueryResolutionDebug(effectiveRequest, Boolean(ebay.queryResolution?.queryContextUsed));
         const mergedSignals = { effectiveContext, ebay, sold, terapeak, social, chart, research };

package/build/validation/threshold-calibration.js

@@ -0,0 +1,311 @@
+/**
+ * Validation Threshold Calibration — Age-Weighted Scoring
+ *
+ * Problem: Current validation thresholds (75/60/45) treat all items the same,
+ * regardless of whether they have eBay sales history or are brand new listings.
+ * New items (< 7 days tracked) get penalized because velocity data is missing,
+ * even when momentum signals are strong.
+ *
+ * Solution: Weighted scoring that adjusts momentum vs. velocity emphasis based
+ * on item age (days tracked):
+ *   - New items (< 7 days):   70% momentum + 30% velocity
+ *   - Established (>= 7 days): 30% momentum + 70% velocity
+ *   - Smooth transition between 0-14 days
+ *
+ * Velocity thresholds by tier: 5 (buy) / 10 (watch) / 20 (skip)
+ * Momentum thresholds by tier: 75 (buy) / 60 (watch) / 45 (skip)
+ */
+// ── Constants ────────────────────────────────────────────────────────────────
+const NEW_ITEM_THRESHOLD_DAYS = 7; // < 7 days = new item
+const WEIGHT_TRANSITION_END = 14; // full transition completes at day 14
+// Momentum thresholds (out of 100)
+const MOMENTUM_THRESHOLDS = {
+    buy: 75,
+    watch: 60,
+    skip: 45,
+};
+// Velocity thresholds (total sold units across day1-day5)
+const VELOCITY_THRESHOLDS = {
+    buy: 5,
+    watch: 10,
+    skip: 20,
+};
+// Default weights for new vs established
+const NEW_ITEM_WEIGHTS = {
+    momentum: 0.7,
+    velocity: 0.3,
+};
+const ESTABLISHED_ITEM_WEIGHTS = {
+    momentum: 0.3,
+    velocity: 0.7,
+};
+// ── Core Functions ───────────────────────────────────────────────────────────
+/**
+ * Calculate scoring weights based on item age (days tracked).
+ *
+ * Days 0-6:  70% momentum / 30% velocity (new item weights)
+ * Days 7-14: Linear transition from new → established weights
+ * Days 14+:  30% momentum / 70% velocity (established item weights)
+ */
+export function calculateAgeAwareWeights(daysTracked) {
+    if (daysTracked === null || daysTracked < 0) {
+        return {
+            weights: { ...NEW_ITEM_WEIGHTS },
+            isNewItem: true,
+        };
+    }
+    if (daysTracked >= WEIGHT_TRANSITION_END) {
+        return {
+            weights: { ...ESTABLISHED_ITEM_WEIGHTS },
+            isNewItem: false,
+        };
+    }
+    if (daysTracked < NEW_ITEM_THRESHOLD_DAYS) {
+        return {
+            weights: { ...NEW_ITEM_WEIGHTS },
+            isNewItem: true,
+        };
+    }
+    // Linear interpolation between NEW_ITEM_THRESHOLD_DAYS and WEIGHT_TRANSITION_END
+    const progress = (daysTracked - NEW_ITEM_THRESHOLD_DAYS) / (WEIGHT_TRANSITION_END - NEW_ITEM_THRESHOLD_DAYS);
+    const momentumWeight = NEW_ITEM_WEIGHTS.momentum +
+        (ESTABLISHED_ITEM_WEIGHTS.momentum - NEW_ITEM_WEIGHTS.momentum) * progress;
+    const velocityWeight = 1 - momentumWeight;
+    return {
+        weights: {
+            momentum: Math.round(momentumWeight * 100) / 100,
+            velocity: Math.round(velocityWeight * 100) / 100,
+        },
+        isNewItem: daysTracked < NEW_ITEM_THRESHOLD_DAYS,
+    };
+}
+/**
+ * Calculate effective thresholds adjusted by the current weights.
+ *
+ * When momentum weight is high (new items), the momentum threshold effectively
+ * matters more, so we lower the velocity bar proportionally, and vice versa.
+ *
+ * The formula scales thresholds by the inverse of their weight:
+ *   effective_momentum_threshold = momentum_threshold * (1 - momentum_weight + momentum_weight * 0.5)
+ *   effective_velocity_threshold = velocity_threshold * (1 - velocity_weight + velocity_weight * 0.5)
+ *
+ * This gives ~25% leeway on the dominant signal while keeping the threshold meaningful.
+ */
+export function calculateEffectiveThresholds(weights) {
+    const momentumScale = 1 - weights.momentum + weights.momentum * 0.5;
+    const velocityScale = 1 - weights.velocity + weights.velocity * 0.5;
+    return {
+        momentumBuy: Math.round(MOMENTUM_THRESHOLDS.buy * momentumScale * 10) / 10,
+        momentumWatch: Math.round(MOMENTUM_THRESHOLDS.watch * momentumScale * 10) / 10,
+        velocityBuy: Math.round(VELOCITY_THRESHOLDS.buy * velocityScale * 10) / 10,
+        velocityWatch: Math.round(VELOCITY_THRESHOLDS.watch * velocityScale * 10) / 10,
+    };
+}
+/**
+ * Classify a momentum score against effective thresholds.
+ */
+function classifyMomentum(score, thresholds) {
+    if (score === null)
+        return 'SKIP';
+    if (score >= thresholds.momentumBuy)
+        return 'BUY';
+    if (score >= thresholds.momentumWatch)
+        return 'WATCH';
+    return 'SKIP';
+}
+/**
+ * Classify velocity (total sold units) against effective thresholds.
+ */
+function classifyVelocity(score, thresholds) {
+    if (score === null)
+        return 'WATCH'; // No velocity data = neutral, not automatic skip
+    if (score >= thresholds.velocityBuy)
+        return 'BUY';
+    if (score >= thresholds.velocityWatch)
+        return 'WATCH';
+    return 'SKIP';
+}
+/**
+ * Extract momentum score from request validation context.
+ * Uses artist momentum score from the request's currentMetrics or item data.
+ */
+function extractMomentumScore(request) {
+    // Check if currentMetrics has a momentum field (may be added by Airtable formula)
+    const _metrics = request.validation.currentMetrics;
+    // Check artist-tier or momentum from the request
+    // The momentum score comes from Artist/Group table, not directly in currentMetrics
+    // It would be available as part of the artistTier context
+    return null; // Fallback — populated by caller if available
+}
+/**
+ * Calculate total velocity (sold units) from current metrics.
+ */
+function extractVelocityScore(request) {
+    const m = request.validation.currentMetrics;
+    const day1 = m.day1Sold ?? 0;
+    const day2 = m.day2Sold ?? 0;
+    const day3 = m.day3Sold ?? 0;
+    const day4 = m.day4Sold ?? 0;
+    const day5 = m.day5Sold ?? 0;
+    const total = day1 + day2 + day3 + day4 + day5;
+    return total > 0 ? total : null;
+}
+/**
+ * Map classification to a 0-100 composite score.
+ */
+function classificationToScore(classification) {
+    switch (classification) {
+        case 'BUY':
+            return 80;
+        case 'WATCH':
+            return 50;
+        case 'SKIP':
+            return 20;
+    }
+}
+/**
+ * Main weighted scoring function.
+ *
+ * Takes the validation request, optional external momentum score, and computes
+ * an age-aware weighted composite score with buy/watch/skip classification.
+ */
+export function computeWeightedValidationScore(request, momentumScoreOverride) {
+    const daysTracked = request.validation.currentMetrics.daysTracked;
+    const { weights, isNewItem } = calculateAgeAwareWeights(daysTracked);
+    const thresholds = calculateEffectiveThresholds(weights);
+    const momentumScore = momentumScoreOverride ?? extractMomentumScore(request);
+    const velocityScore = extractVelocityScore(request);
+    const momentumClass = classifyMomentum(momentumScore, thresholds);
+    const velocityClass = classifyVelocity(velocityScore, thresholds);
+    // Composite: weighted combination of component scores
+    const momentumComponent = classificationToScore(momentumClass);
+    const velocityComponent = classificationToScore(velocityClass);
+    const compositeScore = Math.round(momentumComponent * weights.momentum + velocityComponent * weights.velocity);
+    // Final classification: most restrictive (unless either is BUY)
+    // If either component says BUY, composite is at least WATCH
+    // If both say BUY, composite is BUY
+    let classification;
+    if (momentumClass === 'BUY' && velocityClass === 'BUY') {
+        classification = 'BUY';
+    }
+    else if (momentumClass === 'BUY' || velocityClass === 'BUY') {
+        classification = 'WATCH'; // One strong signal + one neutral = watch
+    }
+    else if (momentumClass === 'SKIP' && velocityClass === 'SKIP') {
+        classification = 'SKIP';
+    }
+    else {
+        classification = 'WATCH'; // Mixed signals = watch
+    }
+    // Override: if composite score is high enough, upgrade to BUY
+    if (compositeScore >= 70 && classification === 'WATCH') {
+        classification = 'BUY';
+    }
+    // Build reasoning
+    const reasoning = [];
+    reasoning.push(`Item age: ${daysTracked !== null ? `${daysTracked} days` : 'unknown'}, ` +
+        `type: ${isNewItem ? 'new' : 'established'}`);
+    reasoning.push(`Weights: momentum ${Math.round(weights.momentum * 100)}%, ` +
+        `velocity ${Math.round(weights.velocity * 100)}%`);
+    reasoning.push(`Effective thresholds — momentum BUY/Watch: ${thresholds.momentumBuy}/${thresholds.momentumWatch}, ` +
+        `velocity BUY/Watch: ${thresholds.velocityBuy}/${thresholds.velocityWatch}`);
+    if (momentumScore !== null) {
+        reasoning.push(`Momentum: ${momentumScore}/100 → ${momentumClass}`);
+    }
+    else {
+        reasoning.push('Momentum: no data → treated as SKIP (neutral for new items)');
+    }
+    if (velocityScore !== null) {
+        reasoning.push(`Velocity: ${velocityScore} units sold (day1-day5) → ${velocityClass}`);
+    }
+    else {
+        reasoning.push('Velocity: no sales data → treated as neutral (WATCH)');
+    }
+    reasoning.push(`Composite score: ${compositeScore}/100 → ${classification}`);
+    return {
+        compositeScore,
+        momentumScore,
+        velocityScore,
+        classification,
+        momentumClassification: momentumClass,
+        velocityClassification: velocityClass,
+        weights,
+        daysTracked,
+        isNewItem,
+        effectiveThresholds: thresholds,
+        reasoning,
+    };
+}
+/**
+ * Convenience: check if the request qualifies for age-aware calibration.
+ */
+export function shouldApplyAgeAwareCalibration(request) {
+    // Apply when the item is in a watchable/tracking state
+    return (request.validation.autoCheckEnabled === true &&
+        request.validation.buyDecision === 'Watching' &&
+        request.validation.automationStatus === 'Watching');
+}
+/**
+ * Compare old flat scoring vs new age-weighted scoring for analysis.
+ */
+export function calibrateAndCompare(itemLabel, daysTracked, momentumScore, velocityScore) {
+    // Old scoring: flat thresholds, 50/50 weight
+    const oldThresholds = {
+        momentumBuy: MOMENTUM_THRESHOLDS.buy,
+        momentumWatch: MOMENTUM_THRESHOLDS.watch,
+        velocityBuy: VELOCITY_THRESHOLDS.buy,
+        velocityWatch: VELOCITY_THRESHOLDS.watch,
+    };
+    const oldMomentumClass = classifyMomentum(momentumScore, oldThresholds);
+    const oldVelocityClass = classifyVelocity(velocityScore, oldThresholds);
+    const oldMomentumComp = classificationToScore(oldMomentumClass);
+    const oldVelocityComp = classificationToScore(oldVelocityClass);
+    const oldCompositeScore = Math.round((oldMomentumComp + oldVelocityComp) / 2);
+    let oldClassification;
+    if (oldMomentumClass === 'BUY' && oldVelocityClass === 'BUY')
+        oldClassification = 'BUY';
+    else if (oldMomentumClass === 'BUY' || oldVelocityClass === 'BUY')
+        oldClassification = 'WATCH';
+    else if (oldMomentumClass === 'SKIP' && oldVelocityClass === 'SKIP')
+        oldClassification = 'SKIP';
+    else
+        oldClassification = 'WATCH';
+    if (oldCompositeScore >= 70 && oldClassification === 'WATCH')
+        oldClassification = 'BUY';
+    // New scoring: age-weighted
+    const { weights, isNewItem } = calculateAgeAwareWeights(daysTracked);
+    const effectiveThresholds = calculateEffectiveThresholds(weights);
+    const newMomentumClass = classifyMomentum(momentumScore, effectiveThresholds);
+    const newVelocityClass = classifyVelocity(velocityScore, effectiveThresholds);
+    const newMomentumComp = classificationToScore(newMomentumClass);
+    const newVelocityComp = classificationToScore(newVelocityClass);
+    const newCompositeScore = Math.round(newMomentumComp * weights.momentum + newVelocityComp * weights.velocity);
+    let newClassification;
+    if (newMomentumClass === 'BUY' && newVelocityClass === 'BUY')
+        newClassification = 'BUY';
+    else if (newMomentumClass === 'BUY' || newVelocityClass === 'BUY')
+        newClassification = 'WATCH';
+    else if (newMomentumClass === 'SKIP' && newVelocityClass === 'SKIP')
+        newClassification = 'SKIP';
+    else
+        newClassification = 'WATCH';
+    if (newCompositeScore >= 70 && newClassification === 'WATCH')
+        newClassification = 'BUY';
+    return {
+        itemLabel,
+        daysTracked,
+        momentumScore,
+        velocityScore,
+        oldMomentumClass,
+        oldVelocityClass,
+        oldCompositeScore,
+        oldClassification,
+        newCompositeScore,
+        newClassification,
+        newWeights: weights,
+        isNewItem,
+        effectiveThresholds,
+        classificationChanged: oldClassification !== newClassification,
+        scoreDelta: newCompositeScore - oldCompositeScore,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ebay-mcp-remote-edition",
-  "version": "4.2.0",
+  "version": "4.2.1",
   "description": "Remote + Local MCP server for eBay APIs - provides access to eBay developer functionality through MCP (Model Context Protocol)",
   "type": "module",
   "main": "build/index.js",