ebay-mcp-remote-edition 4.2.0 → 4.3.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/api/index.js

@@ -6,6 +6,7 @@ import { MessageApi } from '../api/communication/message.js';
 import { NegotiationApi } from '../api/communication/negotiation.js';
 import { NotificationApi } from '../api/communication/notification.js';
 import { DeveloperApi } from '../api/developer/developer.js';
+import { MediaApi } from '../api/media/media.js';
 import { InventoryApi } from '../api/listing-management/inventory.js';
 import { MetadataApi } from '../api/listing-metadata/metadata.js';
 import { TaxonomyApi } from '../api/listing-metadata/taxonomy.js';
@@ -41,6 +42,7 @@ export class EbaySellerApi {
     translation;
     edelivery;
     developer;
+    media;
     trading;
     constructor(config, context) {
         this.client = new EbayApiClient(config, context);
@@ -63,6 +65,7 @@ export class EbaySellerApi {
         this.translation = new TranslationApi(this.client);
         this.edelivery = new EDeliveryApi(this.client);
         this.developer = new DeveloperApi(this.client);
+        this.media = new MediaApi(this.client);
         const tradingClient = new TradingApiClient(this.client);
         this.trading = new TradingApi(tradingClient);
     }

package/build/api/media/media.js

@@ -0,0 +1,124 @@
+import { getBaseUrl } from '../../config/environment.js';
+import axios from 'axios';
+/**
+ * Commerce Media API (v1_beta) - Upload and manage images via eBay Picture Services
+ * Based on: https://developer.ebay.com/api-docs/commerce/media/resources/image/from_url/methods
+ */
+export class MediaApi {
+    client;
+    basePath = '/commerce/media/v1';
+    constructor(client) {
+        this.client = client;
+    }
+    async getAccessToken() {
+        return await this.client.getOAuthClient().getAccessToken();
+    }
+    getMediaBaseUrl() {
+        const env = this.client.getConfig().environment;
+        return getBaseUrl(env);
+    }
+    /**
+     * Upload an image from a public URL to eBay Picture Services.
+     *
+     * Steps:
+     * 1. POST /commerce/media/v1/image/from_url to create the image
+     * 2. GET /commerce/media/v1/image/{imageId} to retrieve the hosted URL
+     *
+     * Supported formats: JPG, GIF, PNG, BMP, TIFF, AVIF, HEIC, WEBP
+     * Max file size: 10MB per image
+     *
+     * @param imageUrl - Public URL of the image to upload
+     * @param description - Optional description for the image
+     * @returns Object with image ID and eBay-hosted image URL
+     */
+    async createImageFromUrl(imageUrl, description) {
+        if (!imageUrl || typeof imageUrl !== 'string') {
+            throw new Error('imageUrl is required and must be a string');
+        }
+        const token = await this.getAccessToken();
+        const baseUrl = this.getMediaBaseUrl();
+        try {
+            // Step 1: Create image from URL
+            const body = { imageUrl };
+            if (description) {
+                Object.assign(body, { description });
+            }
+            const createResponse = await axios.post(`${baseUrl}${this.basePath}/image/from_url`, body, {
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    'Content-Type': 'application/json',
+                    Prefer: 'return=representation',
+                },
+                timeout: 30000,
+            });
+            // Extract image ID from response body or Location header
+            const responseData = createResponse.data;
+            const imageId = typeof responseData.id === 'string'
+                ? responseData.id
+                : createResponse.headers.location?.split('/').pop();
+            if (!imageId) {
+                throw new Error('No image ID returned from create endpoint');
+            }
+            // Step 2: Fetch image details to get the eBay-hosted URL
+            return await this.getImage(imageId);
+        }
+        catch (error) {
+            if (axios.isAxiosError(error)) {
+                const status = error.response?.status;
+                const data = error.response?.data;
+                const message = typeof data === 'object' && data !== null && 'errors' in data
+                    ? data.errors?.[0]?.longMessage ||
+                        data.errors?.[0]?.message ||
+                        error.message
+                    : error.message;
+                throw new Error(`Failed to upload image from URL (status ${status}): ${message}`, {
+                    cause: error,
+                });
+            }
+            throw new Error(`Failed to upload image from URL: ${error instanceof Error ? error.message : 'Unknown error'}`, { cause: error });
+        }
+    }
+    /**
+     * Get image details including the eBay-hosted URL.
+     *
+     * @param imageId - The image ID returned from createImageFromUrl
+     * @returns Image details including hosted URL
+     */
+    async getImage(imageId) {
+        if (!imageId || typeof imageId !== 'string') {
+            throw new Error('imageId is required and must be a string');
+        }
+        const token = await this.getAccessToken();
+        const baseUrl = this.getMediaBaseUrl();
+        try {
+            const response = await axios.get(`${baseUrl}${this.basePath}/image/${imageId}`, {
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    Accept: 'application/json',
+                },
+                timeout: 30000,
+            });
+            const data = response.data;
+            return {
+                id: data.id,
+                imageUrl: data.imageUrl,
+                description: typeof data.description === 'string' ? data.description : undefined,
+            };
+        }
+        catch (error) {
+            if (axios.isAxiosError(error)) {
+                const status = error.response?.status;
+                const data = error.response?.data;
+                const message = typeof data === 'object' && data !== null && 'errors' in data
+                    ? data.errors?.[0]?.longMessage ||
+                        data.errors?.[0]?.message ||
+                        error.message
+                    : error.message;
+                throw new Error(`Failed to get image details (status ${status}): ${message}`, {
+                    cause: error,
+                });
+            }
+            throw new Error(`Failed to get image details: ${error instanceof Error ? error.message : 'Unknown error'}`, { cause: error });
+        }
+    }
+}

package/build/api/trading/trading.js

@@ -51,7 +51,8 @@ export class TradingApi {
         return items?.[0] || result;
     }
     async createListing(item) {
-        return await this.client.execute('AddFixedPriceItem', { Item: item });
+        const transformed = this.client.transformItemForXML(item);
+        return await this.client.execute('AddFixedPriceItem', { Item: transformed });
     }
     async reviseListing(itemId, fields) {
         if (!itemId)

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/inventory.js

@@ -1,4 +1,4 @@
-import { MarketplaceId } from '../../types/ebay-enums.js';
+import { MarketplaceId, Condition } from '../../types/ebay-enums.js';
 import { z } from 'zod';
 import { zodToJsonSchema } from '../../utils/zod-compat.js';
 import { bulkInventoryItemRequestSchema, bulkMigrateRequestSchema, bulkOfferRequestSchema, bulkPriceQuantityRequestSchema, bulkPublishRequestSchema, inventoryItemGroupSchema, inventoryItemSchema, listingFeesRequestSchema, locationSchema, offerSchema, productCompatibilitySchema, } from '../schemas.js';
@@ -29,10 +29,31 @@ export const inventoryTools = [
     },
     {
         name: 'ebay_create_inventory_item',
-        description: 'Create or replace an inventory item.\n\nRequired OAuth Scope: sell.inventory\nMinimum Scope: https://api.ebay.com/oauth/api_scope/sell.inventory',
+        description: 'Create or replace an inventory item.\\n\\nRequired OAuth Scope: sell.inventory\\nMinimum Scope: https://api.ebay.com/oauth/api_scope/sell.inventory',
         inputSchema: {
             sku: z.string().describe('The seller-defined SKU'),
-            inventoryItem: inventoryItemSchema.describe('Inventory item details'),
+            inventoryItem: inventoryItemSchema.describe('Inventory item details (availability, condition, etc.)'),
+            // Accept individual inventory fields as top-level fallback for LLMs that don't wrap in inventoryItem
+            availability: z
+                .any()
+                .optional()
+                .describe('[Fallback] Availability details if inventoryItem not provided'),
+            condition: z
+                .nativeEnum(Condition)
+                .optional()
+                .describe('[Fallback] Item condition if inventoryItem not provided'),
+            conditionDescription: z
+                .string()
+                .optional()
+                .describe('[Fallback] Condition description if inventoryItem not provided'),
+            product: z
+                .any()
+                .optional()
+                .describe('[Fallback] Product details if inventoryItem not provided'),
+            packageWeightAndSize: z
+                .any()
+                .optional()
+                .describe('[Fallback] Package weight/size if inventoryItem not provided'),
         },
         outputSchema: zodToJsonSchema(createInventoryItemOutputSchema, {
             name: 'CreateInventoryItemResponse',

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 },
     },
@@ -68,4 +150,15 @@ export const tradingTools = [
         },
         annotations: { readOnlyHint: false },
     },
+    {
+        name: 'ebay_upload_images',
+        description: 'Upload images to eBay Picture Services using the Commerce Media API and get eBay-hosted image URLs for use in listings.\n\nUploads images from public URLs — eBay fetches and hosts them on their servers. The returned image URLs can be used in ebay_create_listing PicturesDetails.PictureURL array.\n\nSupports: JPG, GIF, PNG, BMP, TIFF, AVIF, HEIC, WEBP. Max 10MB per image.\n\nReturns a result for each uploaded image including the eBay-hosted URL and image ID.',
+        inputSchema: {
+            imageUrls: z
+                .array(z.string().describe('Public URL of the image to upload'))
+                .describe('Array of image URLs to upload (1 or more)'),
+            description: z.string().optional().describe('Optional description for the uploaded images'),
+        },
+        annotations: { readOnlyHint: false },
+    },
 ];

package/build/tools/index.js

@@ -8,6 +8,37 @@ import { getAwaitingFeedbackSchema, getFeedbackRatingSummarySchema, getFeedbackS
 import { bulkUpdateConversationSchema, getConversationSchema, getConversationsSchema, sendMessageSchema, updateConversationSchema, } from '../utils/communication/message.js';
 import { findEligibleItemsSchema, getOffersToBuyersSchema, sendOfferToInterestedBuyersSchema, } from '../utils/communication/negotiation.js';
 import { createDestinationSchema, createSubscriptionFilterSchema, createSubscriptionSchema, deleteDestinationSchema, deleteSubscriptionFilterSchema, deleteSubscriptionSchema, disableSubscriptionSchema, enableSubscriptionSchema, getConfigSchema, getDestinationSchema, getPublicKeySchema, getSubscriptionFilterSchema, getSubscriptionSchema, getSubscriptionsSchema, getTopicSchema, getTopicsSchema, testSubscriptionSchema, updateConfigSchema, updateDestinationSchema, updateSubscriptionSchema, } from '../utils/communication/notification.js';
+/**
+ * Normalize enum values that LLMs often send in wrong formats
+ * (lowercase, plural, hyphenated) to eBay API uppercase snake_case format
+ */
+function normalizeEnumValue(value) {
+    return value.toUpperCase().replace(/-/g, '_').replace(/S$/, ''); // Remove trailing S (e.g., "DAYS" -> "DAY")
+}
+/**
+ * Normalize time duration unit values
+ */
+function normalizeTimeUnit(value) {
+    const normalized = value.toUpperCase().replace(/-/g, '_');
+    const timeUnitMap = {
+        DAY: 'DAY',
+        DAYS: 'DAY',
+        BUSINESS_DAY: 'BUSINESS_DAY',
+        BUSINESS_DAYS: 'BUSINESS_DAY',
+        CALENDAR_DAY: 'CALENDAR_DAY',
+        HOUR: 'HOUR',
+        HOURS: 'HOUR',
+        MINUTE: 'MINUTE',
+        MINUTES: 'MINUTE',
+        SECOND: 'SECOND',
+        SECONDS: 'SECOND',
+        MONTH: 'MONTH',
+        MONTHS: 'MONTH',
+        YEAR: 'YEAR',
+        YEARS: 'YEAR',
+    };
+    return timeUnitMap[normalized] || normalized;
+}
 /**
  * Get all tool definitions for the MCP server
  */
@@ -414,8 +445,17 @@ export async function executeTool(api, toolName, args) {
         case 'ebay_get_return_policies':
             return await api.account.getReturnPolicies(args.marketplaceId);
         // Fulfillment Policy CRUD
-        case 'ebay_create_fulfillment_policy':
-            return await api.account.createFulfillmentPolicy(args.policy);
+        case 'ebay_create_fulfillment_policy': {
+            // Normalize handlingTime.unit to valid enum values (LLMs often send lowercase/plural)
+            const policy = args.policy;
+            if (policy?.handlingTime && typeof policy.handlingTime === 'object') {
+                const ht = policy.handlingTime;
+                if (typeof ht.unit === 'string') {
+                    ht.unit = normalizeTimeUnit(ht.unit);
+                }
+            }
+            return await api.account.createFulfillmentPolicy(policy);
+        }
         case 'ebay_get_fulfillment_policy':
             return await api.account.getFulfillmentPolicy(args.fulfillmentPolicyId);
         case 'ebay_get_fulfillment_policy_by_name':
@@ -495,8 +535,27 @@ export async function executeTool(api, toolName, args) {
             return await api.inventory.getInventoryItems(args.limit, args.offset);
         case 'ebay_get_inventory_item':
             return await api.inventory.getInventoryItem(args.sku);
-        case 'ebay_create_inventory_item':
-            return await api.inventory.createOrReplaceInventoryItem(args.sku, args.inventoryItem);
+        case 'ebay_create_inventory_item': {
+            // Handle both patterns: nested inventoryItem OR flat fields
+            let inventoryItemData = args.inventoryItem;
+            if (!inventoryItemData || typeof inventoryItemData !== 'object') {
+                // Merge fallback fields into inventoryItem
+                const fallbackFields = [
+                    'availability',
+                    'condition',
+                    'conditionDescription',
+                    'product',
+                    'packageWeightAndSize',
+                ];
+                inventoryItemData = {};
+                for (const field of fallbackFields) {
+                    if (args[field] !== undefined) {
+                        inventoryItemData[field] = args[field];
+                    }
+                }
+            }
+            return await api.inventory.createOrReplaceInventoryItem(args.sku, inventoryItemData);
+        }
         case 'ebay_delete_inventory_item':
             return await api.inventory.deleteInventoryItem(args.sku);
         // Bulk Operations
@@ -540,10 +599,20 @@ export async function executeTool(api, toolName, args) {
             return await api.inventory.getOffers(args.sku, args.marketplaceId, args.limit);
         case 'ebay_get_offer':
             return await api.inventory.getOffer(args.offerId);
-        case 'ebay_create_offer':
-            return await api.inventory.createOffer(args.offer);
-        case 'ebay_update_offer':
-            return await api.inventory.updateOffer(args.offerId, args.offer);
+        case 'ebay_create_offer': {
+            const offer = args.offer;
+            if (offer?.format) {
+                offer.format = normalizeEnumValue(offer.format);
+            }
+            return await api.inventory.createOffer(offer);
+        }
+        case 'ebay_update_offer': {
+            const offer = args.offer;
+            if (offer?.format) {
+                offer.format = normalizeEnumValue(offer.format);
+            }
+            return await api.inventory.updateOffer(args.offerId, offer);
+        }
         case 'ebay_delete_offer':
             return await api.inventory.deleteOffer(args.offerId);
         case 'ebay_publish_offer':
@@ -1235,6 +1304,29 @@ export async function executeTool(api, toolName, args) {
             return await api.trading.endListing(args.itemId, args.reason);
         case 'ebay_relist_item':
             return await api.trading.relistItem(args.itemId, args.modifications);
+        case 'ebay_upload_images': {
+            const imageUrls = args.imageUrls;
+            const description = args.description;
+            const results = [];
+            for (const imageUrl of imageUrls) {
+                try {
+                    const result = await api.media.createImageFromUrl(imageUrl, description);
+                    results.push({ success: true, id: result.id, imageUrl: result.imageUrl });
+                }
+                catch (e) {
+                    results.push({
+                        success: false,
+                        error: e instanceof Error ? e.message : String(e),
+                        sourceUrl: imageUrl,
+                    });
+                }
+            }
+            return {
+                uploaded: results.filter((r) => r.success).length,
+                failed: results.filter((r) => !r.success).length,
+                results,
+            };
+        }
         default:
             throw new Error(`Unknown tool: ${toolName}`);
     }

package/build/tools/schemas.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { TimeDurationUnit, RegionType, ShippingCostType, ShippingOptionType, DepositType, RefundMethod, ReturnMethod, ReturnShippingCostPayer, Condition, LengthUnit, WeightUnit, PricingVisibility, FormatType, LocationType, MerchantLocationStatus, DayOfWeek, ReasonForRefund, FundingModel, MessageReferenceType, FeedbackRating, ReportedItemType, } from '../types/ebay-enums.js';
+import { RegionType, ShippingCostType, ShippingOptionType, DepositType, RefundMethod, ReturnMethod, ReturnShippingCostPayer, Condition, LengthUnit, WeightUnit, PricingVisibility, FormatType, LocationType, MerchantLocationStatus, DayOfWeek, ReasonForRefund, FundingModel, MessageReferenceType, FeedbackRating, ReportedItemType, TimeDurationUnit, } from '../types/ebay-enums.js';
 /**
  * Reusable Zod schemas for eBay API tool input validation
  *
@@ -11,7 +11,9 @@ import { TimeDurationUnit, RegionType, ShippingCostType, ShippingOptionType, Dep
 // ============================================================================
 export const timeDurationSchema = z
     .object({
-    unit: z.nativeEnum(TimeDurationUnit),
+    unit: z
+        .nativeEnum(TimeDurationUnit)
+        .describe('Time unit: DAY, BUSINESS_DAY, CALENDAR_DAY, HOUR, MINUTE, SECOND, MONTH, YEAR'),
     value: z.number(),
 })
     .passthrough();
@@ -233,7 +235,7 @@ export const offerSchema = z
     .object({
     sku: z.string(),
     marketplaceId: z.string(),
-    format: z.nativeEnum(FormatType),
+    format: z.string().describe('Listing format: FIXED_PRICE (recommended) or AUCTION'),
     availableQuantity: z.number().optional(),
     categoryId: z.string().optional(),
     listingDescription: z.string().optional(),

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.3.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",
@@ -69,21 +69,21 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.29.0",
     "@upstash/redis": "^1.37.0",
-    "axios": "^1.14.0",
+    "axios": "^1.16.0",
     "chalk": "^5.6.2",
     "cors": "^2.8.6",
     "dotenv-stringify": "^3.0.1",
     "express": "^5.2.1",
-    "fast-xml-parser": "^5.5.10",
+    "fast-xml-parser": "^5.7.2",
     "flatted": "^3.4.2",
     "helmet": "^8.1.0",
-    "jose": "^6.2.2",
+    "jose": "^6.2.3",
     "jsonwebtoken": "^9.0.3",
     "playwright-core": "^1.59.1",
     "prompts": "^2.4.2",
     "update-notifier": "^7.3.1",
     "winston": "^3.19.0",
-    "zod": "^4.3.6",
+    "zod": "^4.4.3",
     "zod-to-json-schema": "^3.25.2"
   },
   "devDependencies": {
@@ -91,27 +91,27 @@
     "@types/cors": "^2.8.19",
     "@types/express": "^5.0.6",
     "@types/jsonwebtoken": "^9.0.10",
-    "@types/node": "^25.5.2",
+    "@types/node": "^25.6.0",
     "@types/prompts": "^2.4.9",
     "@types/supertest": "^7.2.0",
     "@types/update-notifier": "^6.0.8",
-    "@vitest/coverage-v8": "^4.1.2",
-    "@vitest/eslint-plugin": "^1.6.14",
-    "@vitest/ui": "^4.1.2",
-    "eslint": "^10.2.0",
+    "@vitest/coverage-v8": "^4.1.5",
+    "@vitest/eslint-plugin": "^1.6.16",
+    "@vitest/ui": "^4.1.5",
+    "eslint": "^10.3.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-n": "^17.24.0",
-    "nock": "^14.0.12",
+    "nock": "^14.0.14",
     "openapi-typescript": "^7.13.0",
-    "prettier": "^3.8.1",
+    "prettier": "^3.8.3",
     "supertest": "^7.2.2",
-    "tsc-alias": "^1.8.16",
+    "tsc-alias": "^1.8.17",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.58.0",
-    "vitest": "^4.1.2"
+    "typescript-eslint": "^8.59.1",
+    "vitest": "^4.1.5"
   },
-  "packageManager": "pnpm@10.33.0",
+  "packageManager": "pnpm@10.33.2",
   "engines": {
     "node": ">=18.0.0"
   },