ebay-mcp-remote-edition 1.0.0

package/build/api/account-management/account.js

@@ -0,0 +1,301 @@
+/**
+ * Account API - Seller account configuration, policies, programs
+ * Based on: docs/sell-apps/account-management/sell_account_v1_oas3.json
+ */
+export class AccountApi {
+    client;
+    basePath = '/sell/account/v1';
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Get custom policies for the seller
+     */
+    async getCustomPolicies(policyTypes) {
+        const params = policyTypes ? { policy_types: policyTypes } : undefined;
+        return await this.client.get(`${this.basePath}/custom_policy`, params);
+    }
+    /**
+     * Get a specific custom policy
+     */
+    async getCustomPolicy(customPolicyId) {
+        return await this.client.get(`${this.basePath}/custom_policy/${customPolicyId}`);
+    }
+    /**
+     * Get fulfillment policies
+     * @param marketplaceId - Required: The eBay marketplace ID
+     */
+    async getFulfillmentPolicies(marketplaceId) {
+        return await this.client.get(`${this.basePath}/fulfillment_policy`, {
+            marketplace_id: marketplaceId,
+        });
+    }
+    /**
+     * Get payment policies
+     * @param marketplaceId - Required: The eBay marketplace ID
+     */
+    async getPaymentPolicies(marketplaceId) {
+        return await this.client.get(`${this.basePath}/payment_policy`, {
+            marketplace_id: marketplaceId,
+        });
+    }
+    /**
+     * Get return policies
+     * @param marketplaceId - Required: The eBay marketplace ID
+     */
+    async getReturnPolicies(marketplaceId) {
+        return await this.client.get(`${this.basePath}/return_policy`, {
+            marketplace_id: marketplaceId,
+        });
+    }
+    /**
+     * Get seller account privileges
+     */
+    async getPrivileges() {
+        return await this.client.get(`${this.basePath}/privilege`);
+    }
+    // ============================================================
+    // Fulfillment Policy Methods
+    // ============================================================
+    /**
+     * Create a new fulfillment policy
+     */
+    async createFulfillmentPolicy(policy) {
+        return await this.client.post(`${this.basePath}/fulfillment_policy`, policy);
+    }
+    /**
+     * Get a specific fulfillment policy by ID
+     */
+    async getFulfillmentPolicy(fulfillmentPolicyId) {
+        return await this.client.get(`${this.basePath}/fulfillment_policy/${fulfillmentPolicyId}`);
+    }
+    /**
+     * Get a fulfillment policy by name
+     */
+    async getFulfillmentPolicyByName(marketplaceId, name) {
+        return await this.client.get(`${this.basePath}/fulfillment_policy_by_name`, {
+            marketplace_id: marketplaceId,
+            name,
+        });
+    }
+    /**
+     * Update a fulfillment policy
+     */
+    async updateFulfillmentPolicy(fulfillmentPolicyId, policy) {
+        return await this.client.put(`${this.basePath}/fulfillment_policy/${fulfillmentPolicyId}`, policy);
+    }
+    /**
+     * Delete a fulfillment policy
+     */
+    async deleteFulfillmentPolicy(fulfillmentPolicyId) {
+        return await this.client.delete(`${this.basePath}/fulfillment_policy/${fulfillmentPolicyId}`);
+    }
+    // ============================================================
+    // Payment Policy Methods
+    // ============================================================
+    /**
+     * Create a new payment policy
+     */
+    async createPaymentPolicy(policy) {
+        return await this.client.post(`${this.basePath}/payment_policy`, policy);
+    }
+    /**
+     * Get a specific payment policy by ID
+     */
+    async getPaymentPolicy(paymentPolicyId) {
+        return await this.client.get(`${this.basePath}/payment_policy/${paymentPolicyId}`);
+    }
+    /**
+     * Get a payment policy by name
+     */
+    async getPaymentPolicyByName(marketplaceId, name) {
+        return await this.client.get(`${this.basePath}/payment_policy_by_name`, {
+            marketplace_id: marketplaceId,
+            name,
+        });
+    }
+    /**
+     * Update a payment policy
+     */
+    async updatePaymentPolicy(paymentPolicyId, policy) {
+        return await this.client.put(`${this.basePath}/payment_policy/${paymentPolicyId}`, policy);
+    }
+    /**
+     * Delete a payment policy
+     */
+    async deletePaymentPolicy(paymentPolicyId) {
+        return await this.client.delete(`${this.basePath}/payment_policy/${paymentPolicyId}`);
+    }
+    // ============================================================
+    // Return Policy Methods
+    // ============================================================
+    /**
+     * Create a new return policy
+     */
+    async createReturnPolicy(policy) {
+        return await this.client.post(`${this.basePath}/return_policy`, policy);
+    }
+    /**
+     * Get a specific return policy by ID
+     */
+    async getReturnPolicy(returnPolicyId) {
+        return await this.client.get(`${this.basePath}/return_policy/${returnPolicyId}`);
+    }
+    /**
+     * Get a return policy by name
+     */
+    async getReturnPolicyByName(marketplaceId, name) {
+        return await this.client.get(`${this.basePath}/return_policy_by_name`, {
+            marketplace_id: marketplaceId,
+            name,
+        });
+    }
+    /**
+     * Update a return policy
+     */
+    async updateReturnPolicy(returnPolicyId, policy) {
+        return await this.client.put(`${this.basePath}/return_policy/${returnPolicyId}`, policy);
+    }
+    /**
+     * Delete a return policy
+     */
+    async deleteReturnPolicy(returnPolicyId) {
+        return await this.client.delete(`${this.basePath}/return_policy/${returnPolicyId}`);
+    }
+    // ============================================================
+    // Custom Policy Methods
+    // ============================================================
+    /**
+     * Create a new custom policy
+     */
+    async createCustomPolicy(policy) {
+        return await this.client.post(`${this.basePath}/custom_policy`, policy);
+    }
+    /**
+     * Update a custom policy
+     */
+    async updateCustomPolicy(customPolicyId, policy) {
+        return await this.client.put(`${this.basePath}/custom_policy/${customPolicyId}`, policy);
+    }
+    /**
+     * Delete a custom policy
+     */
+    async deleteCustomPolicy(customPolicyId) {
+        return await this.client.delete(`${this.basePath}/custom_policy/${customPolicyId}`);
+    }
+    // ============================================================
+    // KYC, Payments Program, Rate Tables, Sales Tax, Subscription, Programs
+    // ============================================================
+    /**
+     * Get KYC status
+     */
+    async getKyc() {
+        return await this.client.get(`${this.basePath}/kyc`);
+    }
+    /**
+     * Opt-in to a payments program
+     */
+    async optInToPaymentsProgram(marketplaceId, paymentsProgramType) {
+        return await this.client.post(`${this.basePath}/payments_program/${marketplaceId}/${paymentsProgramType}`, {});
+    }
+    /**
+     * Get payments program status
+     */
+    async getPaymentsProgramStatus(marketplaceId, paymentsProgramType) {
+        return await this.client.get(`${this.basePath}/payments_program/${marketplaceId}/${paymentsProgramType}`);
+    }
+    /**
+     * Get rate tables
+     */
+    async getRateTables() {
+        return await this.client.get(`${this.basePath}/rate_table`);
+    }
+    /**
+     * Create or replace sales tax table
+     */
+    async createOrReplaceSalesTax(countryCode, jurisdictionId, salesTaxBase) {
+        return await this.client.put(`${this.basePath}/sales_tax/${countryCode}/${jurisdictionId}`, salesTaxBase);
+    }
+    /**
+     * Bulk create or replace sales tax tables
+     */
+    async bulkCreateOrReplaceSalesTax(requests) {
+        return await this.client.post(`${this.basePath}/sales_tax/bulk_create_or_replace`, {
+            requests,
+        });
+    }
+    /**
+     * Delete sales tax table
+     */
+    async deleteSalesTax(countryCode, jurisdictionId) {
+        return await this.client.delete(`${this.basePath}/sales_tax/${countryCode}/${jurisdictionId}`);
+    }
+    /**
+     * Get sales tax table
+     */
+    async getSalesTax(countryCode, jurisdictionId) {
+        return await this.client.get(`${this.basePath}/sales_tax/${countryCode}/${jurisdictionId}`);
+    }
+    /**
+     * Get all sales tax tables
+     * @param countryCode - Required: Two-letter ISO 3166-1 country code
+     */
+    async getSalesTaxes(countryCode) {
+        return await this.client.get(`${this.basePath}/sales_tax`, {
+            country_code: countryCode,
+        });
+    }
+    /**
+     * Get subscription information
+     */
+    async getSubscription(limitType) {
+        const params = limitType ? { limit: limitType } : undefined;
+        return await this.client.get(`${this.basePath}/subscription`, params);
+    }
+    /**
+     * Opt-in to a program
+     */
+    async optInToProgram(request) {
+        return await this.client.post(`${this.basePath}/program/opt_in`, request);
+    }
+    /**
+     * Opt-out of a program
+     */
+    async optOutOfProgram(request) {
+        return await this.client.post(`${this.basePath}/program/opt_out`, request);
+    }
+    /**
+     * Get opted-in programs
+     */
+    async getOptedInPrograms() {
+        return await this.client.get(`${this.basePath}/program`);
+    }
+    /**
+     * Get seller eligibility for advertising programs
+     * This method allows developers to check the seller eligibility status for eBay advertising programs.
+     * @param programTypes - Optional comma-separated list of program types to check
+     * @param marketplaceId - Required eBay marketplace ID (passed in X-EBAY-C-MARKETPLACE-ID header)
+     */
+    async getAdvertisingEligibility(marketplaceId, programTypes) {
+        const params = programTypes ? { program_types: programTypes } : undefined;
+        return await this.client.get(`${this.basePath}/advertising_eligibility`, params);
+    }
+    /**
+     * Get payments program status for a marketplace
+     * Note: This method is deprecated as all seller accounts globally have been enabled for the new eBay payment and checkout flow.
+     * @param marketplaceId - The eBay marketplace ID
+     * @param paymentsProgramType - The type of payments program
+     */
+    async getPaymentsProgram(marketplaceId, paymentsProgramType) {
+        return await this.client.get(`${this.basePath}/payments_program/${marketplaceId}/${paymentsProgramType}`);
+    }
+    /**
+     * Get payments program onboarding information
+     * Note: This method is deprecated as all seller accounts globally have been enabled for the new eBay payment and checkout flow.
+     * @param marketplaceId - The eBay marketplace ID
+     * @param paymentsProgramType - The type of payments program
+     */
+    async getPaymentsProgramOnboarding(marketplaceId, paymentsProgramType) {
+        return await this.client.get(`${this.basePath}/payments_program/${marketplaceId}/${paymentsProgramType}/onboarding`);
+    }
+}

package/build/api/analytics-and-report/analytics.js

@@ -0,0 +1,102 @@
+/**
+ * Analytics API - Sales and traffic analytics
+ * Based on: docs/sell-apps/analytics-and-report/sell_analytics_v1_oas3.json
+ */
+export class AnalyticsApi {
+    client;
+    basePath = '/sell/analytics/v1';
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Get traffic report for listings
+     * @throws Error if required parameters are missing or invalid
+     */
+    async getTrafficReport(dimension, filter, metric, sort) {
+        // Input validation
+        if (!dimension || typeof dimension !== 'string') {
+            throw new Error('dimension is required and must be a string');
+        }
+        if (!filter || typeof filter !== 'string') {
+            throw new Error('filter is required and must be a string');
+        }
+        if (!metric || typeof metric !== 'string') {
+            throw new Error('metric is required and must be a string');
+        }
+        if (sort !== undefined && typeof sort !== 'string') {
+            throw new Error('sort must be a string when provided');
+        }
+        const params = {
+            dimension,
+            filter,
+            metric,
+        };
+        if (sort)
+            params.sort = sort;
+        try {
+            return await this.client.get(`${this.basePath}/traffic_report`, params);
+        }
+        catch (error) {
+            throw new Error(`Failed to get traffic report: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    /**
+     * Find all seller standards profiles
+     * Endpoint: GET /seller_standards_profile
+     * @throws Error if the request fails
+     */
+    async findSellerStandardsProfiles() {
+        try {
+            return await this.client.get(`${this.basePath}/seller_standards_profile`);
+        }
+        catch (error) {
+            throw new Error(`Failed to find seller standards profiles: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    /**
+     * Get a specific seller standards profile
+     * Endpoint: GET /seller_standards_profile/{program}/{cycle}
+     * @throws Error if required parameters are missing or invalid
+     */
+    async getSellerStandardsProfile(program, cycle) {
+        // Input validation
+        if (!program || typeof program !== 'string') {
+            throw new Error('program is required and must be a string');
+        }
+        if (!cycle || typeof cycle !== 'string') {
+            throw new Error('cycle is required and must be a string');
+        }
+        try {
+            return await this.client.get(`${this.basePath}/seller_standards_profile/${program}/${cycle}`);
+        }
+        catch (error) {
+            throw new Error(`Failed to get seller standards profile: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    /**
+     * Get customer service metrics
+     * Endpoint: GET /customer_service_metric/{customer_service_metric_type}/{evaluation_type}
+     * @throws Error if required parameters are missing or invalid
+     */
+    async getCustomerServiceMetric(customerServiceMetricType, evaluationType, evaluationMarketplaceId) {
+        // Input validation
+        if (!customerServiceMetricType || typeof customerServiceMetricType !== 'string') {
+            throw new Error('customerServiceMetricType is required and must be a string');
+        }
+        if (!evaluationType || typeof evaluationType !== 'string') {
+            throw new Error('evaluationType is required and must be a string');
+        }
+        if (!evaluationMarketplaceId || typeof evaluationMarketplaceId !== 'string') {
+            throw new Error('evaluationMarketplaceId is required and must be a string');
+        }
+        const params = {
+            evaluation_marketplace_id: evaluationMarketplaceId,
+        };
+        try {
+            return await this.client.get(`${this.basePath}/customer_service_metric/${customerServiceMetricType}/${evaluationType}`, params);
+        }
+        catch (error) {
+            throw new Error(`Failed to get customer service metric: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+}

package/build/api/client-trading.js

@@ -0,0 +1,96 @@
+import axios from 'axios';
+import { XMLBuilder, XMLParser } from 'fast-xml-parser';
+import { apiLogger } from '../utils/logger.js';
+const COMPAT_LEVEL = '1451';
+const SITE_ID = '0';
+export class TradingApiClient {
+    restClient;
+    baseUrl;
+    parser;
+    builder;
+    constructor(restClient) {
+        this.restClient = restClient;
+        const env = restClient.getConfig().environment;
+        this.baseUrl = env === 'sandbox' ? 'https://api.sandbox.ebay.com' : 'https://api.ebay.com';
+        this.parser = new XMLParser({
+            ignoreAttributes: false,
+            removeNSPrefix: true,
+            parseTagValue: true,
+            isArray: (_name) => {
+                const arrayTags = [
+                    'Item',
+                    'Errors',
+                    'Error',
+                    'NameValueList',
+                    'Value',
+                    'ShippingServiceOptions',
+                    'InternationalShippingServiceOption',
+                    'PaymentMethods',
+                    'PictureURL',
+                    'CompatibilityList',
+                    'Variation',
+                ];
+                return arrayTags.includes(_name);
+            },
+        });
+        this.builder = new XMLBuilder({
+            ignoreAttributes: false,
+            format: true,
+            suppressEmptyNode: true,
+        });
+    }
+    getBaseUrl() {
+        return this.baseUrl;
+    }
+    async execute(callName, params) {
+        const token = await this.restClient.getOAuthClient().getAccessToken();
+        const requestTag = `${callName}Request`;
+        const responseTag = `${callName}Response`;
+        const xmlObj = {};
+        xmlObj[requestTag] = {
+            '@_xmlns': 'urn:ebay:apis:eBLBaseComponents',
+            ...params,
+        };
+        const xmlBody = `<?xml version="1.0" encoding="utf-8"?>\n${this.builder.build(xmlObj)}`;
+        apiLogger.debug(`Trading API ${callName}`, { xmlBody });
+        let response;
+        try {
+            response = await axios.post(`${this.baseUrl}/ws/api.dll`, xmlBody, {
+                headers: {
+                    'X-EBAY-API-SITEID': SITE_ID,
+                    'X-EBAY-API-COMPATIBILITY-LEVEL': COMPAT_LEVEL,
+                    'X-EBAY-API-CALL-NAME': callName,
+                    'X-EBAY-API-IAF-TOKEN': token,
+                    'Content-Type': 'text/xml',
+                },
+                timeout: 30000,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Unknown HTTP error';
+            throw new Error(`Trading API ${callName} request failed: ${message}`);
+        }
+        let parsed;
+        try {
+            parsed = this.parser.parse(response.data);
+        }
+        catch (e) {
+            throw new Error(`Failed to parse Trading API ${callName} response: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        const result = (parsed[responseTag] || parsed);
+        // Log warnings without failing
+        if (result.Ack === 'Warning') {
+            apiLogger.warn(`Trading API ${callName} returned warnings`, {
+                errors: result.Errors,
+            });
+        }
+        // Check for eBay errors
+        if (result.Ack === 'Failure' || result.Ack === 'PartialFailure') {
+            const errors = result.Errors;
+            const firstError = Array.isArray(errors) ? errors[0] : errors;
+            const message = firstError?.ShortMessage || firstError?.LongMessage || 'Unknown Trading API error';
+            throw new Error(message);
+        }
+        return result;
+    }
+}

package/build/api/client.js

@@ -0,0 +1,173 @@
+import { EbayOAuthClient } from '../auth/oauth.js';
+import { getBaseUrl } from '../config/environment.js';
+import axios from 'axios';
+import { logRequest, logResponse, logErrorResponse } from '../utils/logger.js';
+class RateLimitTracker {
+    requestTimestamps = [];
+    windowMs = 60000;
+    maxRequests = 5000;
+    canMakeRequest() {
+        const now = Date.now();
+        this.requestTimestamps = this.requestTimestamps.filter((timestamp) => now - timestamp < this.windowMs);
+        return this.requestTimestamps.length < this.maxRequests;
+    }
+    recordRequest() {
+        this.requestTimestamps.push(Date.now());
+    }
+    getStats() {
+        const now = Date.now();
+        this.requestTimestamps = this.requestTimestamps.filter((timestamp) => now - timestamp < this.windowMs);
+        return {
+            current: this.requestTimestamps.length,
+            max: this.maxRequests,
+            windowMs: this.windowMs,
+        };
+    }
+}
+export class EbayApiClient {
+    httpClient;
+    authClient;
+    baseUrl;
+    rateLimitTracker;
+    config;
+    getDefaultHeaders() {
+        const headers = {
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+        };
+        if (this.config.contentLanguage) {
+            headers['Content-Language'] = this.config.contentLanguage;
+        }
+        if (this.config.marketplaceId) {
+            headers['X-EBAY-C-MARKETPLACE-ID'] = this.config.marketplaceId;
+        }
+        return headers;
+    }
+    constructor(config, context) {
+        this.config = config;
+        this.authClient = new EbayOAuthClient(config, context);
+        this.baseUrl = getBaseUrl(config.environment);
+        this.rateLimitTracker = new RateLimitTracker();
+        this.httpClient = axios.create({
+            baseURL: this.baseUrl,
+            timeout: 30000,
+            headers: this.getDefaultHeaders(),
+        });
+        this.httpClient.interceptors.request.use(async (config) => {
+            if (!this.rateLimitTracker.canMakeRequest()) {
+                const stats = this.rateLimitTracker.getStats();
+                throw new Error(`Rate limit exceeded: ${stats.current}/${stats.max} requests in ${stats.windowMs}ms window.`);
+            }
+            const token = await this.authClient.getAccessToken();
+            config.headers.Authorization = `Bearer ${token}`;
+            this.rateLimitTracker.recordRequest();
+            logRequest(config.method || 'GET', `${config.baseURL}${config.url}`, config.params, config.data);
+            return config;
+        });
+        this.httpClient.interceptors.response.use((response) => {
+            const remaining = response.headers['x-ebay-c-ratelimit-remaining'];
+            const limit = response.headers['x-ebay-c-ratelimit-limit'];
+            logResponse(response.status, response.statusText, response.data, remaining, limit);
+            return response;
+        }, async (error) => {
+            const config = error.config;
+            if (error.response) {
+                logErrorResponse(error.response.status, error.response.statusText, `${config?.baseURL}${config?.url}`, error.response.data);
+            }
+            if (error.response?.status === 401 && config) {
+                const retryCount = config.__authRetryCount || 0;
+                if (retryCount === 0) {
+                    config.__authRetryCount = 1;
+                    await this.authClient.refreshUserToken();
+                    const newToken = await this.authClient.getAccessToken();
+                    if (config.headers) {
+                        config.headers.Authorization = `Bearer ${newToken}`;
+                    }
+                    return await this.httpClient.request(config);
+                }
+                const ebayError = error.response?.data;
+                const errorMessage = ebayError.errors?.[0]?.longMessage ||
+                    ebayError.errors?.[0]?.message ||
+                    'Invalid access token';
+                throw new Error(`${errorMessage}. Automatic token refresh failed.`);
+            }
+            if (error.response?.status === 429) {
+                const retryAfter = error.response.headers['retry-after'];
+                const waitTime = retryAfter ? parseInt(retryAfter) * 1000 : 60000;
+                throw new Error(`eBay API rate limit exceeded. Retry after ${waitTime / 1000} seconds.`);
+            }
+            if (error.response?.status && error.response.status >= 500 && config) {
+                const retryCount = config.__retryCount || 0;
+                if (retryCount < 3) {
+                    config.__retryCount = retryCount + 1;
+                    const delay = Math.pow(2, retryCount) * 1000;
+                    await new Promise((resolve) => {
+                        setTimeout(resolve, Math.min(delay, 5000));
+                    });
+                    return await this.httpClient.request(config);
+                }
+            }
+            if (axios.isAxiosError(error) && error.response?.data) {
+                const ebayError = error.response.data;
+                const errorMessage = ebayError.errors?.[0]?.longMessage || ebayError.errors?.[0]?.message || error.message;
+                throw new Error(`eBay API Error: ${errorMessage}`);
+            }
+            throw error;
+        });
+    }
+    async initialize() {
+        await this.authClient.initialize();
+    }
+    isAuthenticated() {
+        return this.authClient.isAuthenticated();
+    }
+    hasUserTokens() {
+        return this.authClient.hasUserTokens();
+    }
+    async setUserTokens(accessToken, refreshToken, accessTokenExpiry, refreshTokenExpiry) {
+        await this.authClient.setUserTokens(accessToken, refreshToken, accessTokenExpiry, refreshTokenExpiry);
+    }
+    getTokenInfo() {
+        return this.authClient.getTokenInfo();
+    }
+    getOAuthClient() {
+        return this.authClient;
+    }
+    getRateLimitStats() {
+        return this.rateLimitTracker.getStats();
+    }
+    getConfig() {
+        return this.config;
+    }
+    async refreshUserToken() {
+        await this.authClient.refreshUserToken();
+    }
+    async get(url, params) {
+        const response = await this.httpClient.get(url, { params });
+        return response.data;
+    }
+    async post(url, data, params) {
+        const response = await this.httpClient.post(url, data, { params });
+        return response.data;
+    }
+    async put(url, data, params) {
+        const response = await this.httpClient.put(url, data, { params });
+        return response.data;
+    }
+    async delete(url, params) {
+        const response = await this.httpClient.delete(url, { params });
+        return response.data;
+    }
+    async getWithFullUrl(fullUrl, params) {
+        const token = await this.authClient.getAccessToken();
+        const response = await axios.get(fullUrl, {
+            params,
+            headers: {
+                Authorization: `Bearer ${token}`,
+                ...this.getDefaultHeaders(),
+            },
+            timeout: 30000,
+        });
+        return response.data;
+    }
+}