ebay-mcp 1.17.0 → 1.18.2

package/build/api/order-management/logistics.js

@@ -0,0 +1,150 @@
+import { requestDownloadEffect, } from '../../api/shared/download.js';
+import { optionalStringEffect, requestGetEffect, requestPostEffect, requireObjectEffect, requireStringEffect, } from '../../api/shared/request.js';
+import { Effect } from 'effect';
+/**
+ * Builds the per-call marketplace header; without an override the client's configured
+ * `EBAY_MARKETPLACE_ID` header still satisfies eBay's required `X-EBAY-C-MARKETPLACE-ID`.
+ */
+const marketplaceConfig = (marketplaceId) => marketplaceId === undefined
+    ? undefined
+    : { headers: { 'X-EBAY-C-MARKETPLACE-ID': marketplaceId } };
+/**
+ * Logistics API - shipping quotes, shipments, and shipping labels (limited release; needs the
+ * `sell.logistics` scope). Based on: sell_logistics_v1_oas3.json
+ */
+export class LogisticsApi {
+    basePath = '/sell/logistics/v1_beta';
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Creates a shipping quote with live USPS rates for one package.
+     *
+     * @param input - Generated ShippingQuoteRequest body plus optional marketplace header override.
+     * @returns An Effect that succeeds with eBay's generated ShippingQuote, including its rates.
+     *
+     * @example
+     * ```ts
+     * const quote = await Effect.runPromise(
+     *   logisticsApi.createShippingQuote({ shippingQuoteRequest, marketplaceId: 'EBAY_US' }),
+     * );
+     * ```
+     *
+     * @see https://developer.ebay.com/api-docs/sell/logistics/resources/shipping_quote/methods/createShippingQuote
+     */
+    createShippingQuote = (input) => {
+        const client = this.client;
+        const path = `${this.basePath}/shipping_quote`;
+        return Effect.gen(function* () {
+            const endpointInput = yield* requireObjectEffect(input, 'input');
+            const shippingQuoteRequest = yield* requireObjectEffect(endpointInput.shippingQuoteRequest, 'shippingQuoteRequest');
+            const marketplaceId = yield* optionalStringEffect(endpointInput.marketplaceId, 'marketplaceId');
+            return yield* requestPostEffect(client, path, shippingQuoteRequest, marketplaceConfig(marketplaceId));
+        });
+    };
+    /**
+     * Retrieves a shipping quote and its rates by ID.
+     *
+     * @param input - Shipping quote identifier returned by createShippingQuote.
+     * @returns An Effect that succeeds with eBay's generated ShippingQuote.
+     *
+     * @example
+     * ```ts
+     * const quote = await Effect.runPromise(
+     *   logisticsApi.getShippingQuote({ shippingQuoteId: 'QUOTE-1' }),
+     * );
+     * ```
+     *
+     * @see https://developer.ebay.com/api-docs/sell/logistics/resources/shipping_quote/methods/getShippingQuote
+     */
+    getShippingQuote = (input) => {
+        const client = this.client;
+        const basePath = this.basePath;
+        return Effect.gen(function* () {
+            const endpointInput = yield* requireObjectEffect(input, 'input');
+            const shippingQuoteId = yield* requireStringEffect(endpointInput.shippingQuoteId, 'shippingQuoteId');
+            return yield* requestGetEffect(client, `${basePath}/shipping_quote/${encodeURIComponent(shippingQuoteId)}`);
+        });
+    };
+    /**
+     * Purchases a shipping label by creating a shipment from one rate of a shipping quote. The
+     * seller's billing agreement is charged the rate's base cost plus any added options.
+     *
+     * @param input - Generated CreateShipmentFromQuoteRequest body plus optional marketplace header.
+     * @returns An Effect that succeeds with eBay's generated Shipment, including its shipmentId.
+     *
+     * @example
+     * ```ts
+     * const shipment = await Effect.runPromise(
+     *   logisticsApi.createFromShippingQuote({
+     *     shipmentRequest: { shippingQuoteId: 'QUOTE-1', rateId: 'RATE-1' },
+     *   }),
+     * );
+     * ```
+     *
+     * @see https://developer.ebay.com/api-docs/sell/logistics/resources/shipment/methods/createFromShippingQuote
+     */
+    createFromShippingQuote = (input) => {
+        const client = this.client;
+        const path = `${this.basePath}/shipment/create_from_shipping_quote`;
+        return Effect.gen(function* () {
+            const endpointInput = yield* requireObjectEffect(input, 'input');
+            const shipmentRequest = yield* requireObjectEffect(endpointInput.shipmentRequest, 'shipmentRequest');
+            yield* requireStringEffect(shipmentRequest.shippingQuoteId, 'shipmentRequest.shippingQuoteId');
+            yield* requireStringEffect(shipmentRequest.rateId, 'shipmentRequest.rateId');
+            const marketplaceId = yield* optionalStringEffect(endpointInput.marketplaceId, 'marketplaceId');
+            return yield* requestPostEffect(client, path, shipmentRequest, marketplaceConfig(marketplaceId));
+        });
+    };
+    /**
+     * Retrieves a shipment by ID.
+     *
+     * @param input - Shipment identifier returned by createFromShippingQuote.
+     * @returns An Effect that succeeds with eBay's generated Shipment.
+     *
+     * @example
+     * ```ts
+     * const shipment = await Effect.runPromise(logisticsApi.getShipment({ shipmentId: 'SHIP-1' }));
+     * ```
+     *
+     * @see https://developer.ebay.com/api-docs/sell/logistics/resources/shipment/methods/getShipment
+     */
+    getShipment = (input) => this.shipmentPath(input, '').pipe(Effect.flatMap((path) => requestGetEffect(this.client, path)));
+    /**
+     * Cancels a shipment and deletes its shipping label; eBay refunds the total shipping cost.
+     * A shipment whose label was already used cannot be canceled.
+     *
+     * @param input - Shipment identifier returned by createFromShippingQuote.
+     * @returns An Effect that succeeds with eBay's generated Shipment and its cancellation status.
+     *
+     * @example
+     * ```ts
+     * const canceled = await Effect.runPromise(
+     *   logisticsApi.cancelShipment({ shipmentId: 'SHIP-1' }),
+     * );
+     * ```
+     *
+     * @see https://developer.ebay.com/api-docs/sell/logistics/resources/shipment/methods/cancelShipment
+     */
+    cancelShipment = (input) => this.shipmentPath(input, '/cancel').pipe(Effect.flatMap((path) => requestPostEffect(this.client, path)));
+    /**
+     * Downloads the shipping label generated for a shipment as a PDF.
+     *
+     * @param input - Shipment identifier returned by createFromShippingQuote.
+     * @returns An Effect that succeeds with the label bytes, content type, and file name; fails
+     * with DownloadTooLargeError when the file is too large to return inline over MCP.
+     *
+     * @example
+     * ```ts
+     * const label = await Effect.runPromise(
+     *   logisticsApi.downloadLabelFile({ shipmentId: 'SHIP-1' }),
+     * );
+     * ```
+     *
+     * @see https://developer.ebay.com/api-docs/sell/logistics/resources/shipment/methods/downloadLabelFile
+     */
+    downloadLabelFile = (input) => this.shipmentPath(input, '/download_label_file').pipe(Effect.flatMap((path) => requestDownloadEffect(this.client, path, { headers: { Accept: 'application/pdf' } })));
+    /** Validates a shipment ID and builds its URL-encoded resource path plus `suffix`. */
+    shipmentPath = (input, suffix) => requireObjectEffect(input, 'input').pipe(Effect.flatMap((endpointInput) => requireStringEffect(endpointInput.shipmentId, 'shipmentId')), Effect.map((shipmentId) => `${this.basePath}/shipment/${encodeURIComponent(shipmentId)}${suffix}`));
+}

package/build/api/other/browseMappers.js

@@ -6,16 +6,16 @@
 import { defined } from '../../utils/objects.js';
 import { isRecord } from '../../utils/typeGuards.js';
 /** Read a Browse money field ({ value, currency }). */
-const parseBrowseMoney = (value) => {
-    if (!isRecord(value)) {
+const parseBrowseMoney = (rawMoney) => {
+    if (!isRecord(rawMoney)) {
         return;
     }
-    if (typeof value.value === 'string' && typeof value.currency === 'string') {
-        return { currency: value.currency, value: value.value };
+    if (typeof rawMoney.value === 'string' && typeof rawMoney.currency === 'string') {
+        return { currency: rawMoney.currency, value: rawMoney.value };
     }
 };
 /** Read a string property when present and non-empty. */
-const optionalString = (value) => typeof value === 'string' && value.length > 0 ? value : undefined;
+const optionalString = (rawField) => typeof rawField === 'string' && rawField.length > 0 ? rawField : undefined;
 /** Read a string array property when present. */
 /**
  * Pick the availability container out of a Browse item payload.
@@ -23,16 +23,18 @@ const optionalString = (value) => typeof value === 'string' && value.length > 0
  * eBay returns `estimatedAvailabilities` as either a bare object or a
  * single-element array, depending on the listing.
  */
-const pickAvailabilityContainer = (value) => {
-    if (isRecord(value)) {
-        return value;
+const pickAvailabilityContainer = (estimatedAvailabilities) => {
+    if (isRecord(estimatedAvailabilities)) {
+        return estimatedAvailabilities;
     }
-    if (Array.isArray(value) && isRecord(value[0])) {
-        return value[0];
+    if (Array.isArray(estimatedAvailabilities) && isRecord(estimatedAvailabilities[0])) {
+        return estimatedAvailabilities[0];
     }
 };
-const optionalStringArray = (value) => Array.isArray(value) && value.every((entry) => typeof entry === 'string') && value.length > 0
-    ? value
+const optionalStringArray = (rawField) => Array.isArray(rawField) &&
+    rawField.every((entry) => typeof entry === 'string') &&
+    rawField.length > 0
+    ? rawField
     : undefined;
 /** Seller username and feedback score, both optional on a Browse payload. */
 const pickSeller = (raw) => {
@@ -118,7 +120,7 @@ export const mapItemSummary = (raw) => {
  *
  * @example
  * ```ts
- * const result = mapSearchActiveItemsResponse(rawJson, { query: 'gpu', offset: 0, limit: 20 });
+ * const searchPage = mapSearchActiveItemsResponse(rawJson, { query: 'gpu', offset: 0, limit: 20 });
  * ```
  */
 export const mapSearchActiveItemsResponse = (raw, context) => {

package/build/api/other/browseValidators.js

@@ -45,17 +45,17 @@ const requireIntegerInRange = (value, parameter, min, max) => {
  * are legitimately fractional) closes the gap the MCP schema's `.min(0)`
  * already covers.
  *
- * @param value - Optional price bound already validated as a number >= 0.
+ * @param priceBound - Optional price bound already validated as a number >= 0.
  * @param parameter - Parameter name used in the tagged error.
  * @returns A tagged input error when the bound is not finite, else undefined.
  */
-const nonFinitePriceError = (value, parameter) => {
-    if (value === undefined || Number.isFinite(value)) {
+const nonFinitePriceError = (priceBound, parameter) => {
+    if (priceBound === undefined || Number.isFinite(priceBound)) {
         return;
     }
     return new EndpointInputError({
         parameter,
-        message: `${parameter} must be a finite number; got ${value}`,
+        message: `${parameter} must be a finite number; got ${priceBound}`,
     });
 };
 /** Default page size when limit is omitted. */

package/build/api/other/edelivery.js

@@ -75,8 +75,8 @@ export class EDeliveryApi {
         const path = `${this.basePath}/address_preference`;
         return Effect.gen(function* () {
             const validatedInput = yield* requireObjectEffect(input, 'input');
-            const body = yield* requireObjectEffect(validatedInput.body, 'body');
-            return yield* requestPostEffect(client, path, body);
+            const addressPreference = yield* requireObjectEffect(validatedInput.body, 'body');
+            return yield* requestPostEffect(client, path, addressPreference);
         });
     };
     /**
@@ -116,8 +116,8 @@ export class EDeliveryApi {
         const path = `${this.basePath}/consign_preference`;
         return Effect.gen(function* () {
             const validatedInput = yield* requireObjectEffect(input, 'input');
-            const body = yield* requireObjectEffect(validatedInput.body, 'body');
-            return yield* requestPostEffect(client, path, body);
+            const consignPreference = yield* requireObjectEffect(validatedInput.body, 'body');
+            return yield* requestPostEffect(client, path, consignPreference);
         });
     };
     /**
@@ -250,8 +250,8 @@ export class EDeliveryApi {
         const path = `${this.basePath}/bundle`;
         return Effect.gen(function* () {
             const validatedInput = yield* requireObjectEffect(input, 'input');
-            const body = yield* requireObjectEffect(validatedInput.body, 'body');
-            return yield* requestPostEffect(client, path, body);
+            const bundleRequest = yield* requireObjectEffect(validatedInput.body, 'body');
+            return yield* requestPostEffect(client, path, bundleRequest);
         });
     };
     /**
@@ -340,8 +340,8 @@ export class EDeliveryApi {
         const path = `${this.basePath}/package`;
         return Effect.gen(function* () {
             const validatedInput = yield* requireObjectEffect(input, 'input');
-            const body = yield* requireObjectEffect(validatedInput.body, 'body');
-            return yield* requestPostEffect(client, path, body);
+            const packageRequest = yield* requireObjectEffect(validatedInput.body, 'body');
+            return yield* requestPostEffect(client, path, packageRequest);
         });
     };
     /**
@@ -488,7 +488,7 @@ export class EDeliveryApi {
      *
      * @example
      * ```ts
-     * const response = await Effect.runPromise(
+     * const cancelledPackages = await Effect.runPromise(
      *   edeliveryApi.bulkCancelPackages({ body: { requests: { packageIds: 'PKG123' } } }),
      * );
      * ```
@@ -500,8 +500,8 @@ export class EDeliveryApi {
         const path = `${this.basePath}/package/bulk_cancel_packages`;
         return Effect.gen(function* () {
             const validatedInput = yield* requireObjectEffect(input, 'input');
-            const body = yield* requireObjectEffect(validatedInput.body, 'body');
-            return yield* requestPostEffect(client, path, body);
+            const cancelPackagesRequest = yield* requireObjectEffect(validatedInput.body, 'body');
+            return yield* requestPostEffect(client, path, cancelPackagesRequest);
         });
     };
     /**
@@ -512,7 +512,7 @@ export class EDeliveryApi {
      *
      * @example
      * ```ts
-     * const response = await Effect.runPromise(
+     * const confirmedPackages = await Effect.runPromise(
      *   edeliveryApi.bulkConfirmPackages({ body: { requests: { packageIds: 'PKG123' } } }),
      * );
      * ```
@@ -524,8 +524,8 @@ export class EDeliveryApi {
         const path = `${this.basePath}/package/bulk_confirm_packages`;
         return Effect.gen(function* () {
             const validatedInput = yield* requireObjectEffect(input, 'input');
-            const body = yield* requireObjectEffect(validatedInput.body, 'body');
-            return yield* requestPostEffect(client, path, body);
+            const confirmPackagesRequest = yield* requireObjectEffect(validatedInput.body, 'body');
+            return yield* requestPostEffect(client, path, confirmPackagesRequest);
         });
     };
     /**
@@ -536,7 +536,7 @@ export class EDeliveryApi {
      *
      * @example
      * ```ts
-     * const response = await Effect.runPromise(
+     * const deletedPackages = await Effect.runPromise(
      *   edeliveryApi.bulkDeletePackages({ body: { requests: { packageIds: 'PKG123' } } }),
      * );
      * ```
@@ -548,8 +548,8 @@ export class EDeliveryApi {
         const path = `${this.basePath}/package/bulk_delete_packages`;
         return Effect.gen(function* () {
             const validatedInput = yield* requireObjectEffect(input, 'input');
-            const body = yield* requireObjectEffect(validatedInput.body, 'body');
-            return yield* requestPostEffect(client, path, body);
+            const deletePackagesRequest = yield* requireObjectEffect(validatedInput.body, 'body');
+            return yield* requestPostEffect(client, path, deletePackagesRequest);
         });
     };
     /**
@@ -657,8 +657,8 @@ export class EDeliveryApi {
         const path = `${this.basePath}/complaint`;
         return Effect.gen(function* () {
             const validatedInput = yield* requireObjectEffect(input, 'input');
-            const body = yield* requireObjectEffect(validatedInput.body, 'body');
-            return yield* requestPostEffect(client, path, body);
+            const complaintRequest = yield* requireObjectEffect(validatedInput.body, 'body');
+            return yield* requestPostEffect(client, path, complaintRequest);
         });
     };
 }

package/build/api/other/finding.js

@@ -72,26 +72,26 @@ export const buildFindCompletedItemsParams = (input) => {
     return params;
 };
 /** Read the first string from a Finding JSON array-or-string field. */
-const firstString = (value) => {
-    if (typeof value === 'string' && value.length > 0) {
-        return value;
+const firstString = (rawField) => {
+    if (typeof rawField === 'string' && rawField.length > 0) {
+        return rawField;
     }
-    if (Array.isArray(value) && typeof value[0] === 'string' && value[0].length > 0) {
-        return value[0];
+    if (Array.isArray(rawField) && typeof rawField[0] === 'string' && rawField[0].length > 0) {
+        return rawField[0];
     }
 };
 /** Read the first object from a Finding JSON array-or-object field. */
-const firstRecord = (value) => {
-    if (isRecord(value)) {
-        return value;
+const firstRecord = (rawField) => {
+    if (isRecord(rawField)) {
+        return rawField;
     }
-    if (Array.isArray(value) && isRecord(value[0])) {
-        return value[0];
+    if (Array.isArray(rawField) && isRecord(rawField[0])) {
+        return rawField[0];
     }
 };
 /** Parse a Finding API money field (`@currencyId` + `__value__`). */
-const parseMoney = (value) => {
-    const money = firstRecord(value);
+const parseMoney = (rawMoney) => {
+    const money = firstRecord(rawMoney);
     if (!money) {
         return;
     }
@@ -155,7 +155,7 @@ export const mapFindingItem = (raw) => {
  *
  * @example
  * ```ts
- * const result = mapFindCompletedItemsResponse(rawJson, 'iphone 14');
+ * const soldListings = mapFindCompletedItemsResponse(rawJson, 'iphone 14');
  * ```
  */
 export const mapFindCompletedItemsResponse = (raw, keywords) => {

package/build/api/other/translation.js

@@ -31,8 +31,8 @@ export class TranslationApi {
         const client = this.client;
         const path = `${this.basePath}/translate`;
         return Effect.gen(function* () {
-            const body = yield* requireObjectEffect(input, 'input');
-            return yield* requestPostEffect(client, path, body);
+            const translateRequest = yield* requireObjectEffect(input, 'input');
+            return yield* requestPostEffect(client, path, translateRequest);
         });
     };
 }

package/build/api/other/vero.js

@@ -31,8 +31,8 @@ export class VeroApi {
         const path = `${this.basePath}/vero_report`;
         return Effect.gen(function* () {
             const endpointInput = yield* requireObjectEffect(input, 'input');
-            const body = yield* requireObjectEffect(endpointInput.reportData, 'reportData');
-            return yield* requestPostEffect(client, path, body);
+            const veroReport = yield* requireObjectEffect(endpointInput.reportData, 'reportData');
+            return yield* requestPostEffect(client, path, veroReport);
         });
     };
     /**

package/build/api/shared/download.js

@@ -0,0 +1,79 @@
+import { EbayApiError } from '../../api/shared/request.js';
+import { Data, Effect } from 'effect';
+/**
+ * Largest download returned inline as an embedded MCP resource. Base64 grows the payload by
+ * a third, and some eBay exports (Taxonomy fetchItemAspects) exceed 100 MB compressed.
+ */
+export const MAX_INLINE_DOWNLOAD_BYTES = 25 * 1024 * 1024;
+const DEFAULT_CONTENT_TYPE = 'application/octet-stream';
+const ENCODED_FILE_NAME = /filename\*\s*=\s*(?:UTF-8|utf-8)?'[^']*'([^;]+)/;
+const QUOTED_FILE_NAME = /filename\s*=\s*"([^"]+)"/;
+const BARE_FILE_NAME = /filename\s*=\s*([^;\s]+)/;
+const decodeFileName = (encoded) => {
+    try {
+        return decodeURIComponent(encoded);
+    }
+    catch { }
+};
+/**
+ * Reads the file name eBay advertises in a `content-disposition` header.
+ *
+ * @param header - Raw `content-disposition` value, if the response carried one.
+ * @returns The RFC 5987 `filename*` value when present, else the plain `filename`, else undefined.
+ *
+ * @example
+ * ```ts
+ * fileNameFromDisposition('attachment; filename="report.csv.gz"'); // 'report.csv.gz'
+ * ```
+ */
+export const fileNameFromDisposition = (header) => {
+    if (!header) {
+        return;
+    }
+    const encoded = ENCODED_FILE_NAME.exec(header)?.[1];
+    if (encoded) {
+        return decodeFileName(encoded.trim());
+    }
+    return (QUOTED_FILE_NAME.exec(header)?.[1] ?? BARE_FILE_NAME.exec(header)?.[1])?.trim();
+};
+/** Tagged failure for a download too large to return inline through MCP. */
+export class DownloadTooLargeError extends Data.TaggedError('DownloadTooLargeError') {
+    get message() {
+        return `eBay file from ${this.path} is at least ${this.bytes} bytes, above the ${this.limit}-byte limit for returning files inline over MCP`;
+    }
+}
+/** Size of a download: what was read, or the larger declared length when reading stopped early. */
+const downloadSize = (fileResponse) => Math.max(fileResponse.data.length, Number(fileResponse.headers['content-length']) || 0);
+/**
+ * Downloads a binary eBay resource as an Effect, keeping its content type and file name.
+ * Reading stops as soon as the file is known to exceed {@link MAX_INLINE_DOWNLOAD_BYTES}.
+ *
+ * @param client - eBay REST client that owns auth and transport details.
+ * @param path - eBay REST path, or a full URL when `config.absolute` is set.
+ * @param config - Optional query params, headers, host, or timeout overrides for the request.
+ * @returns An Effect with the file bytes and metadata; fails with EbayApiError, or with
+ * DownloadTooLargeError above {@link MAX_INLINE_DOWNLOAD_BYTES}.
+ *
+ * @example
+ * ```ts
+ * const file = await Effect.runPromise(
+ *   requestDownloadEffect(client, '/sell/feed/v1/task/TASK-1/download_result_file'),
+ * );
+ * ```
+ */
+export const requestDownloadEffect = (client, path, config = {}) => Effect.tryPromise({
+    try: () => client.getForResponse(path, undefined, {
+        ...config,
+        responseType: 'arraybuffer',
+        maxBytes: MAX_INLINE_DOWNLOAD_BYTES,
+    }),
+    catch: (cause) => new EbayApiError({ method: 'GET', path, cause }), // allow-duplicate
+}).pipe(Effect.filterOrFail((fileResponse) => downloadSize(fileResponse) <= MAX_INLINE_DOWNLOAD_BYTES, (fileResponse) => new DownloadTooLargeError({
+    path,
+    bytes: downloadSize(fileResponse),
+    limit: MAX_INLINE_DOWNLOAD_BYTES,
+})), Effect.map((fileResponse) => ({
+    bytes: fileResponse.data,
+    contentType: fileResponse.headers['content-type']?.split(';')[0]?.trim() || DEFAULT_CONTENT_TYPE,
+    fileName: fileNameFromDisposition(fileResponse.headers['content-disposition']),
+})));

package/build/api/shared/location.js

@@ -0,0 +1,33 @@
+import { EbayApiError } from '../../api/shared/request.js';
+import { Effect } from 'effect';
+/**
+ * Reads the created resource ID from a `Location` header and checks it points at the
+ * expected collection, so a malformed or foreign header never becomes an ID.
+ *
+ * @param location - `Location` header from the create response, if any.
+ * @param collectionPath - eBay REST collection path the resource must live under, e.g. `/sell/feed/v1/order_task`.
+ * @returns An Effect with the header and its decoded ID, or an EbayApiError for a missing/invalid header.
+ *
+ * @example
+ * ```ts
+ * const task = yield* locatedResourceId(response.headers.location, '/sell/feed/v1/order_task');
+ * ```
+ */
+export const locatedResourceId = (location, collectionPath) => Effect.try({
+    try: () => {
+        if (!location) {
+            throw new Error('eBay returned no Location header');
+        }
+        const url = new URL(location);
+        const prefix = `${collectionPath}/`;
+        const segment = url.pathname.slice(prefix.length);
+        if (url.protocol !== 'https:' ||
+            !url.pathname.startsWith(prefix) ||
+            !segment ||
+            segment.includes('/')) {
+            throw new Error('eBay returned an invalid resource Location');
+        }
+        return { location, id: decodeURIComponent(segment) };
+    },
+    catch: (cause) => new EbayApiError({ method: 'POST', path: collectionPath, cause }),
+});

package/build/api/shared/request.js

@@ -1,3 +1,4 @@
+import { formatZodIssues } from '../../utils/zodIssues.js';
 import { Data, Effect } from 'effect';
 /** Tagged failure returned by migrated eBay API endpoint Effects. */
 export class EbayApiError extends Data.TaggedError('EbayApiError') {
@@ -9,6 +10,41 @@ export class EbayApiError extends Data.TaggedError('EbayApiError') {
 /** Tagged validation failure returned before an endpoint request is sent. */
 export class EndpointInputError extends Data.TaggedError('EndpointInputError') {
 }
+/**
+ * Parses endpoint input through its Zod schema (the tool's SSOT), reporting a
+ * failure as EndpointInputError so endpoint Effects keep one input-failure type.
+ *
+ * @param schema - Zod endpoint input schema.
+ * @param input - Raw endpoint input.
+ * @param parameter - Parameter named in the failure; defaults to `input`.
+ * @returns An Effect with the decoded input, or EndpointInputError.
+ *
+ * @example
+ * ```ts
+ * const { documentId } = yield* decodeEndpointInputEffect(documentIdInputSchema, input);
+ * ```
+ */
+export const decodeEndpointInputEffect = (schema, input, parameter = 'input') => {
+    const parsedInput = schema.safeParse(input);
+    return parsedInput.success
+        ? Effect.succeed(parsedInput.data)
+        : Effect.fail(new EndpointInputError({ parameter, message: formatZodIssues(parsedInput.error) }));
+};
+/**
+ * Builds the per-call `X-EBAY-C-MARKETPLACE-ID` header for operations whose marketplace
+ * differs from the client's configured `EBAY_MARKETPLACE_ID`.
+ *
+ * @param marketplaceId - eBay marketplace ID, e.g. `EBAY_GB`.
+ * @returns A request config carrying only the marketplace header.
+ *
+ * @example
+ * ```ts
+ * yield* requestGetEffect(client, path, undefined, marketplaceHeader('EBAY_GB'));
+ * ```
+ */
+export const marketplaceHeader = (marketplaceId) => ({
+    headers: { 'X-EBAY-C-MARKETPLACE-ID': marketplaceId },
+});
 /**
  * Builds query params from an endpoint-owned allow-list.
  *
@@ -133,7 +169,7 @@ export const optionalNonNegativeNumberEffect = (value, name) => {
  *
  * @example
  * ```ts
- * const request = yield* requireObjectEffect<CreateOffersRequest>(body, 'offerData');
+ * const createOffersRequest = yield* requireObjectEffect<CreateOffersRequest>(offerData, 'offerData');
  * ```
  */
 export const requireObjectEffect = (value, name) => {
@@ -156,7 +192,7 @@ export const requireObjectEffect = (value, name) => {
  *
  * @example
  * ```ts
- * const response = await Effect.runPromise(requestGetEffect(client, path, params));
+ * const policies = await Effect.runPromise(requestGetEffect(client, path, params));
  * ```
  */
 export const requestGetEffect = (client, path, params, config) => Effect.tryPromise({
@@ -173,21 +209,21 @@ export const requestGetEffect = (client, path, params, config) => Effect.tryProm
  *
  * @param client - eBay REST client that owns auth and transport details.
  * @param path - eBay REST path to request.
- * @param body - Optional JSON body to send.
+ * @param requestBody - Optional JSON body to send.
  * @param config - Optional per-request headers or params, used for endpoint-specific headers.
  * @returns An Effect that succeeds with the generated eBay response DTO.
  *
  * @example
  * ```ts
- * const response = await Effect.runPromise(requestPostEffect(client, path, body));
+ * const createdPolicy = await Effect.runPromise(requestPostEffect(client, path, requestBody));
  * ```
  */
-export const requestPostEffect = (client, path, body, config) => Effect.tryPromise({
+export const requestPostEffect = (client, path, requestBody, config) => Effect.tryPromise({
     try: () => {
         if (config !== undefined) {
-            return client.post(path, body, config);
+            return client.post(path, requestBody, config);
         }
-        return body === undefined ? client.post(path) : client.post(path, body);
+        return requestBody === undefined ? client.post(path) : client.post(path, requestBody);
     },
     catch: (cause) => new EbayApiError({ method: 'POST', path, cause }),
 });
@@ -196,18 +232,40 @@ export const requestPostEffect = (client, path, body, config) => Effect.tryPromi
  *
  * @param client - eBay REST client that owns auth and transport details.
  * @param path - eBay REST path to request.
- * @param body - Optional JSON body to send.
+ * @param requestBody - Optional JSON body to send.
  * @returns An Effect that succeeds with the generated eBay response DTO.
  *
  * @example
  * ```ts
- * const response = await Effect.runPromise(requestPutEffect(client, path, body));
+ * const updatedPolicy = await Effect.runPromise(requestPutEffect(client, path, requestBody));
  * ```
  */
-export const requestPutEffect = (client, path, body, config) => Effect.tryPromise({
-    try: () => config === undefined ? client.put(path, body) : client.put(path, body, config),
+export const requestPutEffect = (client, path, requestBody, config) => Effect.tryPromise({
+    try: () => config === undefined
+        ? client.put(path, requestBody)
+        : client.put(path, requestBody, config),
     catch: (cause) => new EbayApiError({ method: 'PUT', path, cause }),
 });
+/**
+ * Execute a PATCH request as an Effect with typed eBay API errors.
+ *
+ * @param client - eBay REST client that owns auth and transport details.
+ * @param path - eBay REST path to request.
+ * @param requestBody - Optional JSON body to send.
+ * @param config - Optional per-request headers or params, used for endpoint-specific headers.
+ * @returns An Effect that succeeds with the generated eBay response DTO.
+ *
+ * @example
+ * ```ts
+ * await Effect.runPromise(requestPatchEffect(client, path, requestBody, { headers }));
+ * ```
+ */
+export const requestPatchEffect = (client, path, requestBody, config) => Effect.tryPromise({
+    try: () => config === undefined
+        ? client.patch(path, requestBody)
+        : client.patch(path, requestBody, config),
+    catch: (cause) => new EbayApiError({ method: 'PATCH', path, cause }),
+});
 /**
  * Execute a DELETE request as an Effect with typed eBay API errors.
  *