ebay-mcp 1.4.3

package/build/api/client.d.ts

@@ -0,0 +1,89 @@
+import { EbayOAuthClient } from '../auth/oauth.js';
+import type { EbayConfig } from '../types/ebay.js';
+import { type AxiosRequestConfig } from 'axios';
+/**
+ * Base client for making eBay API requests
+ */
+export declare class EbayApiClient {
+    private httpClient;
+    private authClient;
+    private baseUrl;
+    private rateLimitTracker;
+    private config;
+    constructor(config: EbayConfig);
+    /**
+     * Validate that access token is available before making API request
+     */
+    private validateAccessToken;
+    /**
+     * Make a GET request to eBay API
+     */
+    get<T = unknown>(endpoint: string, params?: Record<string, unknown>, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * Make a POST request to eBay API
+     */
+    post<T = unknown>(endpoint: string, data?: unknown, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * Make a PUT request to eBay API
+     */
+    put<T = unknown>(endpoint: string, data?: unknown, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * Make a DELETE request to eBay API
+     */
+    delete<T = unknown>(endpoint: string, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * Initialize the client (load user tokens from storage)
+     */
+    initialize(): Promise<void>;
+    /**
+     * Check if client is authenticated
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Check if user tokens are available
+     */
+    hasUserTokens(): boolean;
+    /**
+     * Set user access and refresh tokens
+     */
+    setUserTokens(accessToken: string, refreshToken: string): Promise<void>;
+    /**
+     * Get token information for debugging
+     */
+    getTokenInfo(): {
+        hasUserToken: boolean;
+        hasAppAccessToken: boolean;
+        scopeInfo?: {
+            tokenScopes: string[];
+            environmentScopes: string[];
+            missingScopes: string[];
+        };
+    };
+    /**
+     * Get the OAuth client instance for advanced operations
+     */
+    getOAuthClient(): EbayOAuthClient;
+    /**
+     * Get rate limit statistics
+     */
+    getRateLimitStats(): {
+        current: number;
+        max: number;
+        windowMs: number;
+    };
+    /**
+     * Get the config object (for accessing environment, etc.)
+     */
+    getConfig(): EbayConfig;
+    /**
+     * Manually refresh user access token using the refresh token
+     * This is useful when you encounter "Invalid access token" errors
+     * The token will be automatically saved to storage after refresh
+     */
+    refreshUserToken(): Promise<void>;
+    /**
+     * Make a GET request with a full URL (for APIs that use different base URLs)
+     * Used by Identity API which uses apiz subdomain
+     */
+    getWithFullUrl<T = unknown>(fullUrl: string, params?: Record<string, unknown>): Promise<T>;
+}

package/build/api/client.js

@@ -0,0 +1,343 @@
+import { EbayOAuthClient } from '../auth/oauth.js';
+import { getBaseUrl } from '../config/environment.js';
+import axios from 'axios';
+/**
+ * Rate limit tracking
+ */
+class RateLimitTracker {
+    requestTimestamps = [];
+    windowMs = 60000; // 1 minute window
+    maxRequests = 5000; // Conservative limit
+    canMakeRequest() {
+        const now = Date.now();
+        // Remove timestamps older than window
+        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,
+        };
+    }
+}
+/**
+ * Base client for making eBay API requests
+ */
+export class EbayApiClient {
+    httpClient;
+    authClient;
+    baseUrl;
+    rateLimitTracker;
+    config;
+    constructor(config) {
+        this.config = config;
+        this.authClient = new EbayOAuthClient(config);
+        this.baseUrl = getBaseUrl(config.environment);
+        this.rateLimitTracker = new RateLimitTracker();
+        this.httpClient = axios.create({
+            baseURL: this.baseUrl,
+            timeout: 30000,
+            headers: {
+                'Content-Type': 'application/json',
+                Accept: 'application/json',
+            },
+        });
+        // Add request interceptor to inject auth token and check rate limits
+        this.httpClient.interceptors.request.use(async (config) => {
+            // Check rate limit before making request
+            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. Please wait before making more requests.`);
+            }
+            const token = await this.authClient.getAccessToken();
+            config.headers.Authorization = `Bearer ${token}`;
+            // Record the request
+            this.rateLimitTracker.recordRequest();
+            // Debug logging: Log outgoing request details
+            console.error('\n🔍 [REQUEST DEBUG]');
+            console.error(`  Method: ${config.method?.toUpperCase()}`);
+            console.error(`  URL: ${config.baseURL}${config.url}`);
+            if (config.params && Object.keys(config.params).length > 0) {
+                console.error(`  Query Params: ${JSON.stringify(config.params, null, 2)}`);
+            }
+            if (config.data) {
+                console.error(`  Request Body: ${JSON.stringify(config.data, null, 2)}`);
+            }
+            return config;
+        }, (error) => console.error(error));
+        // Add response interceptor for error handling and retry logic
+        this.httpClient.interceptors.response.use((response) => {
+            // Extract rate limit info from headers if available
+            const remaining = response.headers['x-ebay-c-ratelimit-remaining'];
+            const limit = response.headers['x-ebay-c-ratelimit-limit'];
+            // Debug logging: Log response details
+            console.error('\n✅ [RESPONSE DEBUG]');
+            console.error(`  Status: ${response.status} ${response.statusText}`);
+            if (remaining && limit) {
+                console.error(`  Rate Limit: ${remaining}/${limit} remaining`);
+            }
+            if (response.data) {
+                const dataStr = JSON.stringify(response.data, null, 2);
+                const preview = dataStr.length > 500 ? dataStr.substring(0, 500) + '...' : dataStr;
+                console.error(`  Response Data: ${preview}`);
+            }
+            return response;
+        }, async (error) => {
+            const axiosError = error;
+            const config = axiosError.config;
+            // Debug logging: Log error response details
+            if (axiosError.response) {
+                console.error('\n❌ [ERROR RESPONSE DEBUG]');
+                console.error(`  Status: ${axiosError.response.status} ${axiosError.response.statusText}`);
+                console.error(`  URL: ${config?.baseURL}${config?.url}`);
+                if (axiosError.response.data) {
+                    console.error(`  Error Data: ${JSON.stringify(axiosError.response.data, null, 2)}`);
+                }
+            }
+            else if (axiosError.request) {
+                console.error('\n❌ [NO RESPONSE DEBUG]');
+                console.error(`  Request was made but no response received`);
+                console.error(`  URL: ${config?.baseURL}${config?.url}`);
+            }
+            else {
+                console.error('\n❌ [REQUEST ERROR DEBUG]');
+                console.error(`  Error: ${axiosError.message}`);
+            }
+            // Handle authentication errors (401 Unauthorized)
+            if (axiosError.response?.status === 401) {
+                const retryCount = config?.__authRetryCount || 0;
+                // Only retry once to avoid infinite loops
+                if (retryCount === 0 && config) {
+                    config.__authRetryCount = 1;
+                    console.error('eBay API authentication error (401). Attempting to refresh user token...');
+                    try {
+                        // Force token refresh by getting a new access token
+                        // The getAccessToken() method will automatically refresh if needed
+                        const newToken = await this.authClient.getAccessToken();
+                        // Update the request with the new token
+                        if (config?.headers) {
+                            config.headers.Authorization = `Bearer ${newToken}`;
+                        }
+                        console.error('Token refreshed successfully. Retrying request...');
+                        // Retry the request with the new token
+                        return await this.httpClient.request(config);
+                    }
+                    catch (refreshError) {
+                        console.error('Failed to refresh token:', refreshError);
+                        // If refresh fails, provide clear guidance
+                        const ebayError = axiosError.response?.data;
+                        const originalError = ebayError.errors?.[0]?.longMessage ||
+                            ebayError.errors?.[0]?.message ||
+                            'Invalid access token';
+                        throw new Error(`${originalError}. ` +
+                            `Token refresh failed: ${refreshError instanceof Error ? refreshError.message : 'Unknown error'}. ` +
+                            `Please use the ebay_set_user_tokens_with_expiry tool to provide valid tokens.`);
+                    }
+                }
+                // If retry already attempted, provide helpful error message
+                const ebayError = axiosError.response?.data;
+                const errorMessage = ebayError.errors?.[0]?.longMessage ||
+                    ebayError.errors?.[0]?.message ||
+                    'Invalid access token';
+                throw new Error(`${errorMessage}. ` +
+                    `Automatic token refresh failed. Please use the ebay_set_user_tokens_with_expiry tool to provide valid tokens.`);
+            }
+            // Handle rate limit errors (429)
+            if (axiosError.response?.status === 429) {
+                const retryAfter = axiosError.response.headers['retry-after'];
+                const waitTime = retryAfter ? parseInt(retryAfter) * 1000 : 60000;
+                throw new Error(`eBay API rate limit exceeded. Retry after ${waitTime / 1000} seconds. ` +
+                    `Consider reducing request frequency or upgrading to user tokens for higher limits.`);
+            }
+            // Handle server errors with retry suggestion (500, 502, 503, 504)
+            if (axiosError.response?.status && axiosError.response.status >= 500 && config) {
+                const retryCount = config.__retryCount || 0;
+                if (retryCount < 3) {
+                    config.__retryCount = retryCount + 1;
+                    const delay = Math.pow(2, retryCount) * 1000; // Exponential backoff
+                    console.error(`eBay API server error (${axiosError.response.status}). ` +
+                        `Retrying in ${delay}ms (attempt ${retryCount + 1}/3)...`);
+                    await new Promise((resolve) => setTimeout(resolve, Math.min(delay, 5000)));
+                    return await this.httpClient.request(config);
+                }
+            }
+            // Handle eBay-specific errors
+            if (axios.isAxiosError(axiosError) && axiosError.response?.data) {
+                const ebayError = axiosError.response.data;
+                const errorMessage = ebayError.errors?.[0]?.longMessage ||
+                    ebayError.errors?.[0]?.message ||
+                    axiosError.message;
+                throw new Error(`eBay API Error: ${errorMessage}`);
+            }
+            throw error;
+        });
+    }
+    /**
+     * Validate that access token is available before making API request
+     */
+    validateAccessToken() {
+        if (!this.authClient.hasUserTokens()) {
+            throw new Error('Access token is missing. Please provide your access token and refresh token by calling ebay_set_user_tokens tool in order to perform API requests.');
+        }
+    }
+    /**
+     * Make a GET request to eBay API
+     */
+    async get(endpoint, params, config) {
+        this.validateAccessToken();
+        const response = await this.httpClient.get(endpoint, { params, ...config });
+        return response.data;
+    }
+    /**
+     * Make a POST request to eBay API
+     */
+    async post(endpoint, data, config) {
+        this.validateAccessToken();
+        const response = await this.httpClient.post(endpoint, data, config);
+        return response.data;
+    }
+    /**
+     * Make a PUT request to eBay API
+     */
+    async put(endpoint, data, config) {
+        this.validateAccessToken();
+        const response = await this.httpClient.put(endpoint, data, config);
+        return response.data;
+    }
+    /**
+     * Make a DELETE request to eBay API
+     */
+    async delete(endpoint, config) {
+        this.validateAccessToken();
+        const response = await this.httpClient.delete(endpoint, config);
+        return response.data;
+    }
+    /**
+     * Initialize the client (load user tokens from storage)
+     */
+    async initialize() {
+        await this.authClient.initialize();
+    }
+    /**
+     * Check if client is authenticated
+     */
+    isAuthenticated() {
+        return this.authClient.isAuthenticated();
+    }
+    /**
+     * Check if user tokens are available
+     */
+    hasUserTokens() {
+        return this.authClient.hasUserTokens();
+    }
+    /**
+     * Set user access and refresh tokens
+     */
+    async setUserTokens(accessToken, refreshToken) {
+        await this.authClient.setUserTokens(accessToken, refreshToken);
+    }
+    /**
+     * Get token information for debugging
+     */
+    getTokenInfo() {
+        return this.authClient.getTokenInfo();
+    }
+    /**
+     * Get the OAuth client instance for advanced operations
+     */
+    getOAuthClient() {
+        return this.authClient;
+    }
+    /**
+     * Get rate limit statistics
+     */
+    getRateLimitStats() {
+        return this.rateLimitTracker.getStats();
+    }
+    /**
+     * Get the config object (for accessing environment, etc.)
+     */
+    getConfig() {
+        return this.config;
+    }
+    /**
+     * Manually refresh user access token using the refresh token
+     * This is useful when you encounter "Invalid access token" errors
+     * The token will be automatically saved to storage after refresh
+     */
+    async refreshUserToken() {
+        await this.authClient.refreshUserToken();
+    }
+    /**
+     * Make a GET request with a full URL (for APIs that use different base URLs)
+     * Used by Identity API which uses apiz subdomain
+     */
+    async getWithFullUrl(fullUrl, params) {
+        this.validateAccessToken();
+        // Check rate limit
+        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. Please wait before making more requests.`);
+        }
+        // Get auth token
+        let token = await this.authClient.getAccessToken();
+        // Record the request
+        this.rateLimitTracker.recordRequest();
+        try {
+            // Make request with full URL
+            const response = await axios.get(fullUrl, {
+                params,
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    'Content-Type': 'application/json',
+                    Accept: 'application/json',
+                },
+                timeout: 30000,
+            });
+            return response.data;
+        }
+        catch (error) {
+            // Handle 401 authentication errors with automatic token refresh
+            if (axios.isAxiosError(error) && error.response?.status === 401) {
+                console.error('eBay API authentication error (401). Attempting to refresh user token...');
+                try {
+                    // Refresh the token
+                    await this.authClient.refreshUserToken();
+                    // Get the new token
+                    token = await this.authClient.getAccessToken();
+                    console.error('Token refreshed successfully. Retrying request...');
+                    // Retry the request with the new token
+                    const response = await axios.get(fullUrl, {
+                        params,
+                        headers: {
+                            Authorization: `Bearer ${token}`,
+                            'Content-Type': 'application/json',
+                            Accept: 'application/json',
+                        },
+                        timeout: 30000,
+                    });
+                    return response.data;
+                }
+                catch (refreshError) {
+                    console.error('Failed to refresh token:', refreshError);
+                    const ebayError = error.response?.data;
+                    const originalError = ebayError.errors?.[0]?.longMessage ||
+                        ebayError.errors?.[0]?.message ||
+                        'Invalid access token';
+                    throw new Error(`${originalError}. ` +
+                        `Token refresh failed: ${refreshError instanceof Error ? refreshError.message : 'Unknown error'}. ` +
+                        `Please use the ebay_set_user_tokens_with_expiry tool to provide valid tokens.`);
+                }
+            }
+            // Re-throw other errors
+            throw error;
+        }
+    }
+}

package/build/api/communication/feedback.d.ts

@@ -0,0 +1,45 @@
+import type { EbayApiClient } from '../client.js';
+/**
+ * Feedback API - Manage buyer and seller feedback
+ * Based on: docs/sell-apps/communication/commerce_feedback_v1_beta_oas3.json
+ */
+export declare class FeedbackApi {
+    private client;
+    private readonly basePath;
+    constructor(client: EbayApiClient);
+    /**
+     * Get items awaiting feedback
+     * Endpoint: GET /awaiting_feedback
+     * @throws Error if the request fails
+     */
+    getAwaitingFeedback(filter?: string, limit?: number, offset?: number): Promise<unknown>;
+    /**
+     * Get feedback for a transaction
+     * Endpoint: GET /feedback
+     * @throws Error if required parameters are missing or invalid
+     */
+    getFeedback(transactionId: string): Promise<unknown>;
+    /**
+     * Get feedback rating summary
+     * Endpoint: GET /feedback_rating_summary
+     * @throws Error if the request fails
+     */
+    getFeedbackRatingSummary(): Promise<unknown>;
+    /**
+     * Leave feedback for a buyer
+     * Endpoint: POST /feedback
+     * @throws Error if required parameters are missing or invalid
+     */
+    leaveFeedbackForBuyer(feedbackData: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Respond to feedback
+     * Endpoint: POST /respond_to_feedback
+     * @throws Error if required parameters are missing or invalid
+     */
+    respondToFeedback(feedbackId: string, responseText: string): Promise<unknown>;
+    /**
+     * Get feedback summary
+     * @deprecated Use getFeedbackRatingSummary() instead
+     */
+    getFeedbackSummary(): Promise<unknown>;
+}

package/build/api/communication/feedback.js

@@ -0,0 +1,119 @@
+/**
+ * Feedback API - Manage buyer and seller feedback
+ * Based on: docs/sell-apps/communication/commerce_feedback_v1_beta_oas3.json
+ */
+export class FeedbackApi {
+    client;
+    basePath = '/commerce/feedback/v1';
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Get items awaiting feedback
+     * Endpoint: GET /awaiting_feedback
+     * @throws Error if the request fails
+     */
+    async getAwaitingFeedback(filter, limit, offset) {
+        const params = {};
+        if (filter !== undefined) {
+            if (typeof filter !== 'string') {
+                throw new Error('filter must be a string when provided');
+            }
+            params.filter = filter;
+        }
+        if (limit !== undefined) {
+            if (typeof limit !== 'number' || limit < 1) {
+                throw new Error('limit must be a positive number when provided');
+            }
+            params.limit = limit;
+        }
+        if (offset !== undefined) {
+            if (typeof offset !== 'number' || offset < 0) {
+                throw new Error('offset must be a non-negative number when provided');
+            }
+            params.offset = offset;
+        }
+        try {
+            return await this.client.get(`${this.basePath}/awaiting_feedback`, params);
+        }
+        catch (error) {
+            throw new Error(`Failed to get awaiting feedback: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    /**
+     * Get feedback for a transaction
+     * Endpoint: GET /feedback
+     * @throws Error if required parameters are missing or invalid
+     */
+    async getFeedback(transactionId) {
+        if (!transactionId || typeof transactionId !== 'string') {
+            throw new Error('transactionId is required and must be a string');
+        }
+        try {
+            return await this.client.get(`${this.basePath}/feedback`, {
+                transaction_id: transactionId,
+            });
+        }
+        catch (error) {
+            throw new Error(`Failed to get feedback: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    /**
+     * Get feedback rating summary
+     * Endpoint: GET /feedback_rating_summary
+     * @throws Error if the request fails
+     */
+    async getFeedbackRatingSummary() {
+        try {
+            return await this.client.get(`${this.basePath}/feedback_rating_summary`);
+        }
+        catch (error) {
+            throw new Error(`Failed to get feedback rating summary: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    /**
+     * Leave feedback for a buyer
+     * Endpoint: POST /feedback
+     * @throws Error if required parameters are missing or invalid
+     */
+    async leaveFeedbackForBuyer(feedbackData) {
+        if (!feedbackData || typeof feedbackData !== 'object') {
+            throw new Error('feedbackData is required and must be an object');
+        }
+        try {
+            return await this.client.post(`${this.basePath}/feedback`, feedbackData);
+        }
+        catch (error) {
+            throw new Error(`Failed to leave feedback: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    /**
+     * Respond to feedback
+     * Endpoint: POST /respond_to_feedback
+     * @throws Error if required parameters are missing or invalid
+     */
+    async respondToFeedback(feedbackId, responseText) {
+        if (!feedbackId || typeof feedbackId !== 'string') {
+            throw new Error('feedbackId is required and must be a string');
+        }
+        if (!responseText || typeof responseText !== 'string') {
+            throw new Error('responseText is required and must be a string');
+        }
+        try {
+            return await this.client.post(`${this.basePath}/respond_to_feedback`, {
+                feedback_id: feedbackId,
+                response_text: responseText,
+            });
+        }
+        catch (error) {
+            throw new Error(`Failed to respond to feedback: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    /**
+     * Get feedback summary
+     * @deprecated Use getFeedbackRatingSummary() instead
+     */
+    async getFeedbackSummary() {
+        return await this.getFeedbackRatingSummary();
+    }
+}

package/build/api/communication/message.d.ts

@@ -0,0 +1,55 @@
+import type { EbayApiClient } from '../client.js';
+/**
+ * Message API - Buyer-seller messaging
+ * Based on: docs/sell-apps/communication/commerce_message_v1_oas3.json
+ */
+export declare class MessageApi {
+    private client;
+    private readonly basePath;
+    constructor(client: EbayApiClient);
+    /**
+     * Bulk update conversation
+     * Endpoint: POST /bulk_update_conversation
+     * @throws Error if required parameters are missing or invalid
+     */
+    bulkUpdateConversation(updateData: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Get conversations
+     * Endpoint: GET /conversation
+     * @throws Error if the request fails
+     */
+    getConversations(filter?: string, limit?: number, offset?: number): Promise<unknown>;
+    /**
+     * Get a specific conversation
+     * Endpoint: GET /conversation/{conversation_id}
+     * @throws Error if required parameters are missing or invalid
+     */
+    getConversation(conversationId: string): Promise<unknown>;
+    /**
+     * Send a message
+     * Endpoint: POST /send_message
+     * @throws Error if required parameters are missing or invalid
+     */
+    sendMessage(messageData: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Update a conversation
+     * Endpoint: POST /update_conversation
+     * @throws Error if required parameters are missing or invalid
+     */
+    updateConversation(updateData: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Search for messages
+     * @deprecated Use getConversations() instead
+     */
+    searchMessages(filter?: string, limit?: number, offset?: number): Promise<unknown>;
+    /**
+     * Get a specific message
+     * @deprecated Use getConversation() instead
+     */
+    getMessage(messageId: string): Promise<unknown>;
+    /**
+     * Reply to a message
+     * @deprecated Use sendMessage() instead
+     */
+    replyToMessage(messageId: string, messageContent: string): Promise<unknown>;
+}