ebay-mcp 1.13.2 → 1.14.0

package/build/api/clientRequestError.js

@@ -0,0 +1,23 @@
+import { Data } from 'effect';
+/** Tagged failure raised inside the REST client's request/retry Effect. */
+export class EbayClientRequestError extends Data.TaggedError('EbayClientRequestError') {
+}
+/**
+ * Builds a tagged REST-client request error while omitting absent optional fields.
+ *
+ * @param input - Request failure fields captured by the REST client.
+ * @returns Tagged client request error used as the internal request Effect failure.
+ *
+ * @example
+ * ```ts
+ * clientRequestError({ kind: 'httpStatus', method: 'GET', url, message, status: 429 });
+ * ```
+ */
+export const clientRequestError = ({ kind, method, url, message, status, cause, }) => new EbayClientRequestError({
+    kind,
+    method,
+    url,
+    message,
+    ...(status === undefined ? {} : { status }),
+    ...(cause === undefined ? {} : { cause }),
+});

package/build/api/clientTrading.js

@@ -0,0 +1,213 @@
+import XmlBuilder from 'fast-xml-builder';
+import { XMLParser } from 'fast-xml-parser';
+import { TradingApiFailure } from '../api/clientTradingError.js';
+import { EbayApiError } from '../api/shared/request.js';
+import { getBaseUrl } from '../config/environment.js';
+import { getErrorMessage } from '../utils/errors.js';
+import { httpRequestEffect } from '../utils/http.js';
+import { apiLogger } from '../utils/logger.js';
+import { isRecord } from '../utils/typeGuards.js';
+import { Effect } from 'effect';
+const COMPAT_LEVEL = '1451';
+const SITE_ID = '0';
+const TRADING_ENDPOINT_PATH = '/ws/api.dll';
+const TRADING_XMLNS = 'urn:ebay:apis:eBLBaseComponents';
+const buildTradingPath = (baseUrl) => `${baseUrl}${TRADING_ENDPOINT_PATH}`;
+const buildTradingHeaders = (callName) => ({
+    'X-EBAY-API-SITEID': SITE_ID,
+    'X-EBAY-API-COMPATIBILITY-LEVEL': COMPAT_LEVEL,
+    'X-EBAY-API-CALL-NAME': callName,
+    'Content-Type': 'text/xml',
+});
+const buildTradingXmlBody = (builder, requestTag, params) => {
+    const xmlObject = {
+        [requestTag]: {
+            '@_xmlns': TRADING_XMLNS,
+            ...params,
+        },
+    };
+    return `<?xml version="1.0" encoding="utf-8"?>\n${builder.build(xmlObject)}`;
+};
+const createTradingApiError = ({ callName, path }, message, cause) => new EbayApiError({
+    method: 'POST',
+    path,
+    cause: new TradingApiFailure({
+        callName,
+        path,
+        message: `Trading API ${callName} ${message}`,
+        ...(cause === undefined ? {} : { cause }),
+    }),
+});
+const authorizeTradingHeaders = ({ restClient, headers, callName, path, }) => {
+    if (restClient.getConfig().disableAuthHeader) {
+        return Effect.succeed(headers);
+    }
+    return restClient
+        .getOAuthClient()
+        .getAccessToken()
+        .pipe(Effect.mapError((error) => createTradingApiError({ callName, path }, `token acquisition failed: ${getErrorMessage(error)}`)), Effect.map((token) => ({ ...headers, 'X-EBAY-API-IAF-TOKEN': token })));
+};
+const postTradingXml = ({ path, headers, xmlBody, callName, }) => httpRequestEffect({
+    method: 'POST',
+    url: path,
+    headers,
+    body: xmlBody,
+    timeoutMs: 30_000,
+    responseType: 'text',
+}).pipe(Effect.mapError((error) => createTradingApiError({ callName, path }, `request failed: ${getErrorMessage(error)}`)));
+const parseTradingXml = ({ parser, responseText, callName, path, }) => Effect.try({
+    try: () => parser.parse(responseText),
+    catch: (error) => new EbayApiError({
+        method: 'POST',
+        path,
+        cause: new TradingApiFailure({
+            callName,
+            path,
+            message: `Failed to parse Trading API ${callName} response: ${getErrorMessage(error)}`,
+            cause: error,
+        }),
+    }),
+}).pipe(Effect.flatMap((parsedValue) => {
+    if (isRecord(parsedValue)) {
+        return Effect.succeed(parsedValue);
+    }
+    return Effect.fail(createTradingApiError({ callName, path }, 'response must be an object'));
+}));
+const readTradingPayload = (parsed, responseTag, { callName, path }) => {
+    const resultValue = parsed[responseTag] === undefined ? parsed : parsed[responseTag];
+    if (isRecord(resultValue)) {
+        return Effect.succeed(resultValue);
+    }
+    return Effect.fail(createTradingApiError({ callName, path }, 'response payload is not an object'));
+};
+const extractTradingErrorMessage = (errors) => {
+    const firstError = Array.isArray(errors) ? errors[0] : errors;
+    if (!isRecord(firstError)) {
+        return 'Trading API returned a failure without an error message';
+    }
+    const shortMessage = firstError.ShortMessage;
+    if (typeof shortMessage === 'string' && shortMessage !== '') {
+        return shortMessage;
+    }
+    const longMessage = firstError.LongMessage;
+    if (typeof longMessage === 'string' && longMessage !== '') {
+        return longMessage;
+    }
+    return 'Trading API returned a failure without an error message';
+};
+const validateTradingAck = (result, { callName, path }) => {
+    if (result.Ack === 'Warning') {
+        apiLogger.warn(`Trading API ${callName} returned warnings`, {
+            errors: result.Errors,
+        });
+    }
+    if (result.Ack === 'Failure' || result.Ack === 'PartialFailure') {
+        return Effect.fail(new EbayApiError({
+            method: 'POST',
+            path,
+            cause: new TradingApiFailure({
+                callName,
+                path,
+                message: extractTradingErrorMessage(result.Errors),
+                cause: result.Errors,
+            }),
+        }));
+    }
+    return Effect.succeed(result);
+};
+/**
+ * XML-based client for eBay Trading API calls that are not covered by REST APIs.
+ */
+export class TradingApiClient {
+    restClient;
+    baseUrl;
+    parser;
+    builder;
+    constructor(restClient) {
+        this.restClient = restClient;
+        const config = restClient.getConfig();
+        this.baseUrl = getBaseUrl(config.environment, config.apiBaseUrl);
+        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,
+        });
+    }
+    /**
+     * Return the Trading API base URL for the configured eBay environment.
+     *
+     * @returns The Trading API base URL derived from the configured environment.
+     *
+     * @example
+     * ```ts
+     * const baseUrl = tradingClient.getTradingBaseUrl();
+     * ```
+     */
+    getTradingBaseUrl = () => this.baseUrl;
+    /**
+     * Execute a named Trading API call with XML request/response conversion.
+     *
+     * @param callName - Trading API call name, such as GetItem or AddFixedPriceItem.
+     * @param params - XML request payload fields nested under the generated request tag.
+     * @returns An Effect that succeeds with the parsed response payload.
+     *
+     * @example
+     * ```ts
+     * const result = await Effect.runPromise(
+     *   tradingClient.execute('GetItem', { ItemID: '12345' }),
+     * );
+     * ```
+     */
+    execute = (callName, params) => {
+        const tradingClient = this;
+        const requestTag = `${callName}Request`;
+        const responseTag = `${callName}Response`;
+        const path = buildTradingPath(tradingClient.baseUrl);
+        const headers = buildTradingHeaders(callName);
+        const xmlBody = buildTradingXmlBody(tradingClient.builder, requestTag, params);
+        apiLogger.debug(`Trading API ${callName}`, { xmlBody });
+        return Effect.gen(function* () {
+            const authorizedHeaders = yield* authorizeTradingHeaders({
+                restClient: tradingClient.restClient,
+                headers,
+                callName,
+                path,
+            });
+            const response = yield* postTradingXml({
+                path,
+                headers: authorizedHeaders,
+                xmlBody,
+                callName,
+            });
+            const parsed = yield* parseTradingXml({
+                parser: tradingClient.parser,
+                responseText: response.data,
+                callName,
+                path,
+            });
+            const result = yield* readTradingPayload(parsed, responseTag, { callName, path });
+            return yield* validateTradingAck(result, { callName, path });
+        });
+    };
+}

package/build/api/clientTradingError.js

@@ -0,0 +1,4 @@
+import { Data } from 'effect';
+/** Tagged cause attached to `EbayApiError` for Trading XML failures. */
+export class TradingApiFailure extends Data.TaggedError('TradingApiFailure') {
+}

package/build/api/communication/feedback.js

@@ -1,5 +1,5 @@
-import { getPaginatedWithContextError, getPathWithContextError } from './shared.js';
-import { withApiError } from '../../api/shared/request.js';
+import { buildEndpointParams, optionalNonNegativeNumberEffect, optionalPositiveNumberEffect, optionalStringEffect, requestGetEffect, requestPostEffect, requireObjectEffect, requireStringEffect, } from '../../api/shared/request.js';
+import { Effect } from 'effect';
 /**
  * Feedback API - Manage buyer and seller feedback
  * Based on: docs/sell-apps/communication/commerce_feedback_v1_beta_oas3.json
@@ -11,70 +11,158 @@ export class FeedbackApi {
         this.client = client;
     }
     /**
-     * Get items awaiting feedback
-     * Endpoint: GET /awaiting_feedback
-     * @param filter API filter expression.
-     * @param limit Maximum number of records to return.
-     * @param offset Zero-based pagination offset.
-     * @throws Error if the request fails
+     * Retrieves line items awaiting feedback.
+     *
+     * @param input - Optional filter, pagination, and sort query parameters.
+     * @returns An Effect that succeeds with eBay's generated AwaitingFeedbackResponse.
+     *
+     * @example
+     * ```ts
+     * const awaiting = await Effect.runPromise(
+     *   feedbackApi.getAwaitingFeedback({ filter: 'userRole:SELLER', limit: 25 }),
+     * );
+     * ```
+     *
+     * @see https://developer.ebay.com/api-docs/commerce/feedback/resources/awaiting_feedback/methods/getItemsAwaitingFeedback
      */
-    async getAwaitingFeedback(filter, limit, offset) {
-        return await getPaginatedWithContextError(this.client, `${this.basePath}/awaiting_feedback`, 'Failed to get awaiting feedback', filter, limit, offset);
-    }
-    /**
-     * 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');
-        }
-        return await withApiError('Failed to get feedback', () => this.client.get(`${this.basePath}/feedback`, {
-            transaction_id: transactionId,
-        }));
-    }
+    getAwaitingFeedback = (input = {}) => {
+        const client = this.client;
+        const path = `${this.basePath}/awaiting_feedback`;
+        return Effect.gen(function* () {
+            const filter = yield* optionalStringEffect(input.filter, 'filter');
+            const limit = yield* optionalPositiveNumberEffect(input.limit, 'limit');
+            const offset = yield* optionalNonNegativeNumberEffect(input.offset, 'offset');
+            const sort = yield* optionalStringEffect(input.sort, 'sort');
+            const params = buildEndpointParams({
+                filter: { wireName: 'filter', value: filter },
+                limit: { wireName: 'limit', value: limit },
+                offset: { wireName: 'offset', value: offset },
+                sort: { wireName: 'sort', value: sort },
+            });
+            return yield* requestGetEffect(client, path, params);
+        });
+    };
     /**
-     * Get feedback rating summary
-     * Endpoint: GET /feedback_rating_summary
-     * @throws Error if the request fails
+     * Retrieves feedback for a specified eBay user.
+     *
+     * @param input - Required user and feedback type plus optional endpoint filters.
+     * @returns An Effect that succeeds with eBay's generated GetFeedbackResponse.
+     *
+     * @example
+     * ```ts
+     * const feedback = await Effect.runPromise(
+     *   feedbackApi.getFeedback({ userId: 'seller_123', feedbackType: 'FEEDBACK_RECEIVED' }),
+     * );
+     * ```
+     *
+     * @see https://developer.ebay.com/api-docs/commerce/feedback/resources/feedback/methods/getFeedback
      */
-    async getFeedbackRatingSummary() {
-        return await getPathWithContextError(this.client, `${this.basePath}/feedback_rating_summary`, 'Failed to get feedback rating summary');
-    }
+    getFeedback = (input) => {
+        const client = this.client;
+        const path = `${this.basePath}/feedback`;
+        return Effect.gen(function* () {
+            const request = yield* requireObjectEffect(input, 'input');
+            const userId = yield* requireStringEffect(request.userId, 'userId');
+            const feedbackType = yield* requireStringEffect(request.feedbackType, 'feedbackType');
+            const feedbackId = yield* optionalStringEffect(request.feedbackId, 'feedbackId');
+            const filter = yield* optionalStringEffect(request.filter, 'filter');
+            const limit = yield* optionalPositiveNumberEffect(request.limit, 'limit');
+            const listingId = yield* optionalStringEffect(request.listingId, 'listingId');
+            const offset = yield* optionalNonNegativeNumberEffect(request.offset, 'offset');
+            const orderLineItemId = yield* optionalStringEffect(request.orderLineItemId, 'orderLineItemId');
+            const sort = yield* optionalStringEffect(request.sort, 'sort');
+            const transactionId = yield* optionalStringEffect(request.transactionId, 'transactionId');
+            const params = buildEndpointParams({
+                userId: { wireName: 'user_id', value: userId },
+                feedbackType: { wireName: 'feedback_type', value: feedbackType },
+                feedbackId: { wireName: 'feedback_id', value: feedbackId },
+                filter: { wireName: 'filter', value: filter },
+                limit: { wireName: 'limit', value: limit },
+                listingId: { wireName: 'listing_id', value: listingId },
+                offset: { wireName: 'offset', value: offset },
+                orderLineItemId: { wireName: 'order_line_item_id', value: orderLineItemId },
+                sort: { wireName: 'sort', value: sort },
+                transactionId: { wireName: 'transaction_id', value: transactionId },
+            });
+            return yield* requestGetEffect(client, path, params);
+        });
+    };
     /**
-     * Leave feedback for a buyer
-     * Endpoint: POST /feedback
-     * @throws Error if required parameters are missing or invalid
+     * Retrieves a feedback rating summary for a user.
+     *
+     * @param input - Required eBay user ID and rating summary filter.
+     * @returns An Effect that succeeds with eBay's generated GetFeedbackRatingSummaryResponse.
+     *
+     * @example
+     * ```ts
+     * const summary = await Effect.runPromise(
+     *   feedbackApi.getFeedbackRatingSummary({
+     *     userId: 'seller_123',
+     *     filter: 'ratingType:OVERALL_EXPERIENCE',
+     *   }),
+     * );
+     * ```
+     *
+     * @see https://developer.ebay.com/api-docs/commerce/feedback/resources/feedback_rating_summary/methods/getFeedbackRatingSummary
      */
-    async leaveFeedbackForBuyer(feedbackData) {
-        if (!feedbackData || typeof feedbackData !== 'object') {
-            throw new Error('feedbackData is required and must be an object');
-        }
-        return await withApiError('Failed to leave feedback', () => this.client.post(`${this.basePath}/feedback`, feedbackData));
-    }
+    getFeedbackRatingSummary = (input) => {
+        const client = this.client;
+        const path = `${this.basePath}/feedback_rating_summary`;
+        return Effect.gen(function* () {
+            const request = yield* requireObjectEffect(input, 'input');
+            const userId = yield* requireStringEffect(request.userId, 'userId');
+            const filter = yield* requireStringEffect(request.filter, 'filter');
+            const params = buildEndpointParams({
+                userId: { wireName: 'user_id', value: userId },
+                filter: { wireName: 'filter', value: filter },
+            });
+            return yield* requestGetEffect(client, path, params);
+        });
+    };
     /**
-     * Respond to feedback
-     * Endpoint: POST /respond_to_feedback
-     * @throws Error if required parameters are missing or invalid
+     * Leaves feedback for the user's order partner.
+     *
+     * @param feedbackData - Generated LeaveFeedbackRequest body.
+     * @returns An Effect that succeeds with eBay's generated LeaveFeedbackResponse.
+     *
+     * @example
+     * ```ts
+     * const feedback = await Effect.runPromise(
+     *   feedbackApi.leaveFeedbackForBuyer({ commentText: 'Great buyer', commentType: 'POSITIVE' }),
+     * );
+     * ```
+     *
+     * @see https://developer.ebay.com/api-docs/commerce/feedback/resources/feedback/methods/leaveFeedback
      */
-    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');
-        }
-        return await withApiError('Failed to respond to feedback', () => this.client.post(`${this.basePath}/respond_to_feedback`, {
-            feedback_id: feedbackId,
-            response_text: responseText,
-        }));
-    }
+    leaveFeedbackForBuyer = (feedbackData) => {
+        const client = this.client;
+        const path = `${this.basePath}/feedback`;
+        return Effect.gen(function* () {
+            const body = yield* requireObjectEffect(feedbackData, 'feedbackData');
+            return yield* requestPostEffect(client, path, body);
+        });
+    };
     /**
-     * Get feedback summary
-     * @deprecated Use getFeedbackRatingSummary() instead
+     * Responds to feedback received from another eBay user.
+     *
+     * @param response - Generated RespondToFeedbackRequest body.
+     * @returns An Effect that succeeds with eBay's generated empty response.
+     *
+     * @example
+     * ```ts
+     * await Effect.runPromise(
+     *   feedbackApi.respondToFeedback({ feedbackId: 'feedback-1', responseText: 'Thank you' }),
+     * );
+     * ```
+     *
+     * @see https://developer.ebay.com/api-docs/commerce/feedback/resources/respond_to_feedback/methods/respondToFeedback
      */
-    async getFeedbackSummary() {
-        return await this.getFeedbackRatingSummary();
-    }
+    respondToFeedback = (response) => {
+        const client = this.client;
+        const path = `${this.basePath}/respond_to_feedback`;
+        return Effect.gen(function* () {
+            const body = yield* requireObjectEffect(response, 'response');
+            return yield* requestPostEffect(client, path, body);
+        });
+    };
 }