ebay-mcp 1.18.3 → 2.0.0

package/README.md

@@ -5,7 +5,7 @@
 </p>
 
 <p align="center">
-  <strong>The eBay MCP server — give Claude, Cursor, and any AI assistant full access to eBay's Sell APIs. 384 tools for inventory, orders, marketing, and analytics, running locally with your own keys.</strong>
+  <strong>The eBay MCP server — give Claude, Cursor, and any AI assistant full access to eBay's Sell APIs. 380 tools for inventory, orders, marketing, and analytics, running locally with your own keys.</strong>
 </p>
 
 <p align="center"><sub>Unofficial, open-source project — not affiliated with, authorized, or endorsed by eBay Inc.</sub></p>
@@ -20,7 +20,7 @@
 </p>
 
 <p align="center">
-  <img src="https://img.shields.io/badge/tools-384-8957e5?logo=ebay&logoColor=white" alt="384 eBay API tools" />
+  <img src="https://img.shields.io/badge/tools-380-8957e5?logo=ebay&logoColor=white" alt="380 eBay API tools" />
   <img src="https://img.shields.io/badge/Sell%20API%20coverage-100%25-success" alt="100% eBay Sell API coverage" />
   <img src="https://img.shields.io/badge/Model%20Context%20Protocol-compatible-000000" alt="Model Context Protocol compatible" />
   <img src="https://img.shields.io/badge/tests-1%2C000%2B%20passing-3fb950?logo=vitest&logoColor=white" alt="Over 1,000 passing tests" />
@@ -33,7 +33,7 @@
 
 ---
 
-**eBay MCP** is a local [Model Context Protocol](https://modelcontextprotocol.io) server that connects AI assistants — [Claude Desktop](https://claude.ai/download), [Claude Code](https://code.claude.com/docs/en/overview), [Cursor](https://cursor.com/), [Cline](https://cline.bot/), [Windsurf](https://windsurf.com/), [Zed](https://zed.dev/), [Continue.dev](https://docs.continue.dev/), [Roo Code](https://roocode.com/), and [Amazon Q Developer](https://aws.amazon.com/q/developer/) — directly to **[eBay's Sell APIs](https://developer.ebay.com/api-docs/sell/static/overview.html)**. It exposes **384 tools** spanning **100% of eBay's Sell API surface** (360 unique endpoints) for inventory management, order fulfillment, promoted-listings marketing, analytics, and developer tooling. Everything runs on your machine over STDIO or local HTTP — **no cloud relay**, and your eBay credentials never leave your computer.
+**eBay MCP** is a local [Model Context Protocol](https://modelcontextprotocol.io) server that connects AI assistants — [Claude Desktop](https://claude.ai/download), [Claude Code](https://code.claude.com/docs/en/overview), [Cursor](https://cursor.com/), [Cline](https://cline.bot/), [Windsurf](https://windsurf.com/), [Zed](https://zed.dev/), [Continue.dev](https://docs.continue.dev/), [Roo Code](https://roocode.com/), and [Amazon Q Developer](https://aws.amazon.com/q/developer/) — directly to **[eBay's Sell APIs](https://developer.ebay.com/api-docs/sell/static/overview.html)**. It exposes **380 tools** spanning **100% of the eBay Sell, Commerce and Developer APIs it tracks** (356 unique endpoints) for inventory management, order fulfillment, promoted-listings marketing, analytics, and developer tooling. Everything runs on your machine over STDIO or local HTTP — **no cloud relay**, and your eBay credentials never leave your computer.
 
 > **Disclaimer:** Unofficial, third-party project — **not affiliated with or endorsed by eBay Inc.** Provided "as is" without warranty. You are responsible for complying with [eBay's API License Agreement](https://developer.ebay.com/join/api-license-agreement) and [data-handling requirements](https://developer.ebay.com/api-docs/static/data-handling-update.html), keeping your credentials secure, and staying within rate limits. Test in sandbox before production. See [LICENSE](LICENSE).
 
@@ -59,7 +59,7 @@
 
 ## Features
 
-- **384 eBay API tools** — 100% coverage of the eBay Sell APIs across inventory, orders, marketing, analytics, metadata, taxonomy, and developer tooling.
+- **380 eBay API tools** — 100% coverage of the eBay Sell APIs across inventory, orders, marketing, analytics, metadata, taxonomy, and developer tooling.
 - **9 AI clients, auto-configured** — Claude Desktop, Cursor, Zed, Cline, Continue.dev, Windsurf, Roo Code, Claude Code CLI, and Amazon Q Developer.
 - **OAuth 2.0 built in** — full user-token management with automatic refresh, and smart fallback from user tokens (10k–50k req/day) to client credentials (1k req/day).
 - **Resilient by default** — automatic retry with exponential backoff on `429` rate limits, and consistent, loud error surfacing.
@@ -87,7 +87,7 @@ Use this map when deciding which tool family to expose, or when asking an assist
 | `analytics` | Traffic reports, seller standards, and customer-service metrics | "Show my seller standards profile." |
 | `communication` | Buyer-seller messaging, negotiations, notifications, and feedback | "Show recent buyer messages that need a response." |
 | `metadata` / `taxonomy` | Category trees, aspects, item conditions, return-policy metadata, tax jurisdictions, vehicle compatibility, shipping carriers/services/locations, handling times, expired categories, bulk aspect export, and charitable organizations | "Find required item aspects for this category." |
-| `other` | Identity, VeRO, translation, and international shipping support APIs (Compliance tools remain but report eBay's 2026-03-30 decommission) | "Show my current seller identity details." |
+| `other` | Identity, VeRO, translation, and international shipping support APIs | "Show my current seller identity details." |
 | `developer` / `token-management` | Rate limits, signing keys, OAuth URLs, token refresh, and diagnostics | "Check my eBay API rate limits." |
 | `trading` | Legacy XML listing create, revise, relist, and end operations for fixed-price listings and auctions | "Create a fixed-price listing draft from this SKU." |
 | `connector` | ChatGPT connector search/fetch tools over the eBay MCP catalogue | "Search the eBay tool catalogue for order tools." |
@@ -251,9 +251,23 @@ billing agreement; `ebay_cancel_shipment` refunds it while the label is unused.
   release.
 
 Eligible keysets add the scope to `EBAY_OAUTH_SCOPES`, keeping the other scopes they need, and
-repeat OAuth consent. eBay requires Digital Signatures on Finances calls for sellers in the EU and
-UK, and this server does not sign requests yet, so those sellers get eBay's signature error from
-the Finances tools.
+repeat OAuth consent.
+
+**Digital signatures (EU/UK sellers).** eBay requires
+[Digital Signatures](https://developer.ebay.com/develop/guides/digital-signatures-for-apis) on every
+Finances API call and on `issueRefund` for sellers domiciled in the EU or UK; without them eBay
+answers `403 Missing x-ebay-signature-key header`. To enable signing:
+
+1. Run `ebay_create_signing_key` (ED25519 is recommended) and keep the response — eBay never shows
+   the private key again.
+2. Set `EBAY_SIGNING_KEY_JWE` to its `jwe` and `EBAY_SIGNING_PRIVATE_KEY` to its `privateKey`
+   (the base64 value as returned, or a PEM key), then restart the server.
+
+Those calls then carry the `x-ebay-signature-key`, `Content-Digest`, `Signature-Input`, and
+`Signature` headers (RFC 9421). Other calls are never signed, and nothing changes while the two
+variables are unset. Behind `EBAY_MCP_API_BASE_URL`, calls are signed for the eBay host and path
+they reach (`api.ebay.com` or `apiz.ebay.com`), so the proxy must forward eBay's `Host` header and
+the original eBay path.
 
 ## eBay MCP vs. the raw eBay API
 
@@ -267,7 +281,7 @@ Both talk to the same eBay endpoints — the difference is everything you'd othe
 | Input validation | Zod schemas + TypeScript types on every tool | None — you validate your own payloads |
 | Setup | One wizard (`npm run setup`) | Per-call auth, headers, and marketplace wiring |
 | AI client support | 9 clients auto-configured | Not applicable |
-| API coverage | 384 tools across 100% of the Sell APIs, ready to call | Build each request from the docs |
+| API coverage | 380 tools across 100% of the Sell APIs, ready to call | Build each request from the docs |
 | Hosting | Runs locally, no cloud relay | Your own infrastructure |
 
 ## One-click AI setup
@@ -392,6 +406,8 @@ EBAY_MARKETPLACE_ID=EBAY_US         # default marketplace (overridable per tool)
 # EBAY_SITE_ID=0                    # Trading API site override; defaults from EBAY_MARKETPLACE_ID
 EBAY_CONTENT_LANGUAGE=en-US         # default request content language
 EBAY_USER_REFRESH_TOKEN=your_token  # for higher rate limits
+# EBAY_SIGNING_KEY_JWE=<jwe>         # Digital Signatures for EU/UK sellers (jwe from ebay_create_signing_key)
+# EBAY_SIGNING_PRIVATE_KEY=<key>     # privateKey from the same response (base64 PKCS#8 or PEM)
 EBAY_MCP_UI=on                      # interactive MCP Apps views (beta); "off" forces plain JSON
 EBAY_MCP_TOOLS=all                  # tool exposure: "all", "dynamic", or a family list (see below)
 EBAY_READ_ONLY=false                # when true, only register read-only tools (gets/lists/searches)
@@ -428,7 +444,7 @@ User-token limits vary by account tier (Individual 10k · Commercial 25k · Ente
 
 ### MCP client compatibility
 
-Auto-configured by `npm run setup`. Requires [Node.js](https://nodejs.org/en) ≥ 20 and MCP protocol 1.0+ over STDIO (default) or HTTP.
+Auto-configured by `npm run setup`. Requires [Node.js](https://nodejs.org/en) ≥ 24 and MCP protocol 1.0+ over STDIO (default) or HTTP.
 
 | Client                 | Platform              | Config path                                                                  |
 | ---------------------- | --------------------- | ---------------------------------------------------------------------------- |
@@ -447,9 +463,9 @@ Auto-configured by `npm run setup`. Requires [Node.js](https://nodejs.org/en)
 ## Available tools
 
 <details open>
-<summary><strong>384 tools by category (100% Sell API coverage)</strong></summary>
+<summary><strong>380 tools by category (100% Sell API coverage)</strong></summary>
 
-**384 tools**, 100% Sell API coverage, organized by category. Each link points to the tool definitions and handlers in [`src/tools/categories/`](src/tools/categories/):
+**380 tools**, 100% Sell API coverage, organized by category. Each link points to the tool definitions and handlers in [`src/tools/categories/`](src/tools/categories/):
 
 | Category | What you can do |
 | --- | --- |
@@ -466,7 +482,7 @@ Auto-configured by `npm run setup`. Requires [Node.js](https://nodejs.org/en)
 | [Communication](src/tools/categories/communication.ts) | Buyer–seller messaging, negotiations, notifications, feedback |
 | [Metadata](src/tools/categories/metadata.ts) | Return policies, sales-tax jurisdictions, automotive compatibility, shipping carriers/services/locations, handling times |
 | [Taxonomy](src/tools/categories/taxonomy.ts) | Category trees, item aspects, item conditions, expired categories, bulk aspect export, and charitable organizations ([`charity.ts`](src/tools/categories/charity.ts), Charity API) |
-| [Other](src/tools/categories/other.ts) | Identity, VeRO, translation, and international shipping support APIs (Compliance tools report eBay decommission) |
+| [Other](src/tools/categories/other.ts) | Identity, VeRO, translation, and international shipping support APIs |
 | [Trading (legacy XML)](src/tools/categories/trading.ts) | Fixed-price and auction listing create, revise, relist, end |
 | [Developer](src/tools/categories/developer.ts) | Rate limits, signing keys, client registration |
 | [Token Management](src/tools/categories/tokenManagement.ts) | OAuth URL generation and token management |
@@ -537,7 +553,7 @@ Common tasks, phrased as you'd ask your AI assistant:
 <details>
 <summary><strong>What is the eBay MCP server?</strong></summary>
 
-A local [Model Context Protocol](https://modelcontextprotocol.io) server that exposes **384 tools** covering **100% of eBay's Sell APIs** (360 endpoints) to AI assistants — inventory, order fulfillment, marketing, analytics, and developer tools.
+A local [Model Context Protocol](https://modelcontextprotocol.io) server that exposes **380 tools** covering **100% of the eBay Sell, Commerce and Developer APIs it tracks** (356 endpoints) to AI assistants — inventory, order fulfillment, marketing, analytics, and developer tools.
 
 </details>
 
@@ -572,7 +588,7 @@ Interactive [MCP Apps](#interactive-ui-mcp-apps) views only appear on hosts that
 <details>
 <summary><strong>How many eBay APIs and tools does it cover?</strong></summary>
 
-384 tools across 360 unique endpoints — 100% of eBay's Sell APIs.
+380 tools across 356 unique endpoints — 100% of the eBay Sell, Commerce and Developer APIs it tracks.
 
 </details>
 
@@ -593,7 +609,7 @@ It runs entirely on your machine over STDIO (or local HTTP). There is no cloud r
 <details>
 <summary><strong>What do I need to get started?</strong></summary>
 
-Node.js ≥ 20, a free [eBay Developer Account](https://developer.ebay.com/) (Client ID + Client Secret), then run `npm run setup`.
+Node.js ≥ 24, a free [eBay Developer Account](https://developer.ebay.com/) (Client ID + Client Secret), then run `npm run setup`.
 
 </details>
 
@@ -685,6 +701,8 @@ pnpm test && pnpm test:integration         # Vitest unit + integration
 pnpm build                                 # Build to build/
 ```
 
+To run the CI gate locally in Docker before pushing, use [act](https://nektosact.com): `act workflow_dispatch -W .github/workflows/ci.yml`. The root `.actrc` picks the runner image and keeps the pnpm store outside the workspace.
+
 ## Resources
 
 Project docs:

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

@@ -608,12 +608,12 @@ export class AccountApi {
      *
      * @example
      * ```ts
-     * const kyc = await Effect.runPromise(accountApi.getKyc({}));
+     * const kyc = await Effect.runPromise(accountApi.getKYC({}));
      * ```
      *
      * @see https://developer.ebay.com/api-docs/sell/account/resources/kyc/methods/getKYC
      */
-    getKyc = (_input = {}) => requestGetEffect(this.client, `${ACCOUNT_BASE_PATH}/kyc`);
+    getKYC = (_input = {}) => requestGetEffect(this.client, `${ACCOUNT_BASE_PATH}/kyc`);
     /**
      * Retrieves seller advertising-program eligibility for one marketplace.
      *

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

@@ -299,12 +299,6 @@ export class AccountV2Api {
      * Changes one or more seller preferences for one marketplace (PATCH: send only
      * the preferences being changed).
      *
-     * eBay's OAS3 spec references an undefined `SetUserPreferencesRequest`, so the
-     * generated body type is `unknown`. The body is typed from the tool schema,
-     * which mirrors the definition in eBay's published Account v2 spec: the
-     * `*PreferencesType` containers returned by getUserPreferences, with
-     * SetItemsAwaitingPaymentPreferencesType for unpaid-item settings.
-     *
      * @param input - Marketplace header and the preferences PATCH body.
      * @returns An Effect that succeeds when eBay returns 204 No Content.
      *

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

@@ -14,7 +14,9 @@ const pageQuery = (input) => buildEndpointParams({
 const filterQuery = (filter) => buildEndpointParams({ filter: { wireName: 'filter', value: filter } });
 /**
  * Finances API - payouts, transactions, transfers, seller funds, billing activity, and order
- * earnings. Every operation except getBillingActivities is served from the apiz host.
+ * earnings. Every operation except getBillingActivities is served from the apiz host. Every
+ * call is digitally signed when signing credentials are configured, as eBay requires for
+ * EU/UK sellers.
  */
 export class FinancesApi {
     client;
@@ -28,8 +30,8 @@ export class FinancesApi {
     getFromApiz = (path, params, marketplaceId) => {
         const client = this.client;
         const config = marketplaceId === undefined
-            ? { absolute: true }
-            : { absolute: true, headers: { 'X-EBAY-C-MARKETPLACE-ID': marketplaceId } };
+            ? { absolute: true, signed: true }
+            : { absolute: true, signed: true, headers: { 'X-EBAY-C-MARKETPLACE-ID': marketplaceId } };
         return Effect.tryPromise({
             try: () => {
                 const { environment, apiBaseUrl } = client.getConfig();
@@ -281,8 +283,8 @@ export class FinancesApi {
         return Effect.gen(function* () {
             const validatedInput = yield* decodeEndpointInputEffect(getBillingActivitiesInputSchema, input);
             const config = validatedInput.acceptLanguage === undefined
-                ? undefined
-                : { headers: { 'Accept-Language': validatedInput.acceptLanguage } };
+                ? { signed: true }
+                : { signed: true, headers: { 'Accept-Language': validatedInput.acceptLanguage } };
             return yield* requestGetEffect(client, `${BASE_PATH}/billing_activity`, pageQuery(validatedInput), config);
         });
     };

package/build/api/client/ebayApiClient.js

@@ -1,7 +1,8 @@
 import { EbayOAuthClient } from '../../auth/oauth.js';
 import { clientRequestError, } from '../../api/client/ebayClientRequestError.js';
 import { RateLimitTracker } from '../../api/client/rateLimitTracker.js';
-import { getBaseUrl } from '../../config/environment.js';
+import { parseSigningPrivateKey, signEbayRequest } from '../../api/client/signEbayRequest.js';
+import { getBaseUrl, getIdentityBaseUrl } from '../../config/environment.js';
 import { getErrorMessage } from '../../utils/errors.js';
 import { httpRequestEffect, isHttpError, } from '../../utils/http.js';
 import { isRecord } from '../../utils/typeGuards.js';
@@ -22,6 +23,38 @@ const deleteHeader = (headers, name) => {
         }
     }
 };
+/**
+ * Serialize a body exactly as the HTTP adapter would so its Content-Digest
+ * matches the bytes on the wire. Multipart and Blob bodies never reach here:
+ * fetch streams them, so they cannot be digested up front.
+ */
+const serializeSignedBody = (requestBody) => {
+    if (requestBody === undefined || requestBody === null) {
+        return { wireBody: requestBody };
+    }
+    if (typeof requestBody === 'string' || requestBody instanceof Uint8Array) {
+        return { wireBody: requestBody, digestBytes: requestBody };
+    }
+    if (requestBody instanceof ArrayBuffer) {
+        return { wireBody: requestBody, digestBytes: new Uint8Array(requestBody) };
+    }
+    if (requestBody instanceof URLSearchParams) {
+        const encoded = requestBody.toString();
+        return { wireBody: requestBody, digestBytes: encoded };
+    }
+    const json = JSON.stringify(requestBody);
+    return { wireBody: json, digestBytes: json };
+};
+// A proxy forwards eBay's Host header and path, so the signature covers the eBay URL.
+const ebayFacingUrl = (url, ebayBaseUrl, apiBaseUrl) => apiBaseUrl !== undefined && url.startsWith(apiBaseUrl)
+    ? `${ebayBaseUrl}${url.slice(apiBaseUrl.length)}`
+    : url;
+const SIGNATURE_ERROR_PATTERN = /signature/i;
+const TRAILING_PERIOD_PATTERN = /\.?$/;
+/** True when an eBay error body points at a missing or rejected digital signature. */
+const isSignatureFailure = (detail) => detail !== undefined && SIGNATURE_ERROR_PATTERN.test(detail);
+/** Remediation appended to signature failures when the server has no signing credentials. */
+const SIGNING_SETUP_HINT = ' eBay requires Digital Signatures on this call for EU/UK sellers. Create a key with ebay_create_signing_key, then set EBAY_SIGNING_KEY_JWE (the jwe value) and EBAY_SIGNING_PRIVATE_KEY (the privateKey value) and restart the server.';
 /**
  * Remediation hint for a token failure, matched to the token the request needs.
  *
@@ -46,6 +79,8 @@ export class EbayApiClient {
     rateLimitTracker;
     config;
     timeoutMs = 30_000;
+    /** Parsed signing key, cached after the first signed request. */
+    signingKey;
     /**
      * Build default request headers based on configured marketplace and language.
      */
@@ -70,6 +105,47 @@ export class EbayApiClient {
         this.baseUrl = getBaseUrl(config.environment, config.apiBaseUrl);
         this.rateLimitTracker = new RateLimitTracker();
     }
+    /** Parse (once) and return the configured signing key. */
+    getSigningKey(privateKey) {
+        if (this.signingKey === undefined) {
+            this.signingKey = parseSigningPrivateKey(privateKey);
+        }
+        return this.signingKey;
+    }
+    signRequest(method, url, options) {
+        const { signing, environment, apiBaseUrl } = this.config;
+        if (!options.signed || signing === undefined) {
+            return Effect.succeed({ wireBody: options.data, signatureHeaders: {} });
+        }
+        if (options.data instanceof FormData || options.data instanceof Blob) {
+            return Effect.fail(clientRequestError({
+                kind: 'signing',
+                method,
+                url,
+                message: 'Multipart and Blob request bodies cannot be digitally signed.',
+            }));
+        }
+        const { wireBody, digestBytes } = serializeSignedBody(options.data);
+        // Absolute signed endpoints are the apiz-hosted Finances calls.
+        const ebayBaseUrl = options.absolute
+            ? getIdentityBaseUrl(environment)
+            : getBaseUrl(environment);
+        const signedUrl = ebayFacingUrl(url, ebayBaseUrl, apiBaseUrl);
+        return Effect.try({
+            try: () => {
+                const signingKey = this.getSigningKey(signing.privateKey);
+                const signatureHeaders = signEbayRequest({ method, url: signedUrl, bodyBytes: digestBytes }, signing.keyJwe, signingKey);
+                return { wireBody, signatureHeaders };
+            },
+            catch: (cause) => clientRequestError({
+                kind: 'signing',
+                method,
+                url,
+                message: `Failed to sign request: ${getErrorMessage(cause)}`,
+                cause,
+            }),
+        });
+    }
     /**
      * Acquire the access token a request should authenticate with.
      *
@@ -207,6 +283,8 @@ export class EbayApiClient {
                 }
                 headers.Authorization = `Bearer ${token}`;
             }
+            const { wireBody, signatureHeaders } = yield* this.signRequest(method, url, options);
+            Object.assign(headers, signatureHeaders);
             this.rateLimitTracker.recordRequest();
             logRequest(method, url, options.params, isBinaryBody(options.data) ? '[binary body]' : options.data);
             return yield* httpRequestEffect({
@@ -214,7 +292,7 @@ export class EbayApiClient {
                 url,
                 params: options.params,
                 headers,
-                body: options.data,
+                body: wireBody,
                 timeoutMs: options.timeoutMs ?? this.timeoutMs,
                 responseType: options.responseType,
                 maxBytes: options.maxBytes,
@@ -311,14 +389,8 @@ export class EbayApiClient {
             })));
         }
         if (error.status != null) {
-            return Effect.fail(clientRequestError({
-                kind: 'httpStatus',
-                method,
-                url,
-                status: error.status,
-                message: `eBay API Error: ${this.ebayErrorDetail(error.data) ?? error.message}${this.ebayErrorBody(error.data)}`,
-                cause: error,
-            }));
+            const statusError = this.httpStatusError(error, context);
+            return Effect.fail(statusError);
         }
         return Effect.fail(clientRequestError({
             kind: 'transport',
@@ -328,6 +400,29 @@ export class EbayApiClient {
             cause: error,
         }));
     }
+    httpStatusError(error, context) {
+        const { method, url, options } = context;
+        const detail = this.ebayErrorDetail(error.data);
+        // Without credentials, a signature rejection is a setup problem: show setup guidance.
+        if (options.signed && isSignatureFailure(detail) && this.config.signing === undefined) {
+            return clientRequestError({
+                kind: 'signing',
+                method,
+                url,
+                status: error.status,
+                message: `${detail?.replace(TRAILING_PERIOD_PATTERN, '.')}${SIGNING_SETUP_HINT}`,
+                cause: error,
+            });
+        }
+        return clientRequestError({
+            kind: 'httpStatus',
+            method,
+            url,
+            status: error.status,
+            message: `eBay API Error: ${detail || error.message}${this.ebayErrorBody(error.data)}`,
+            cause: error,
+        });
+    }
     /**
      * Make a GET request to eBay API
      */
@@ -340,6 +435,7 @@ export class EbayApiClient {
             timeoutMs: config?.timeoutMs,
             maxBytes: config?.maxBytes,
             tokenType: config?.tokenType,
+            signed: config?.signed,
         });
     }
     /**
@@ -355,6 +451,7 @@ export class EbayApiClient {
             timeoutMs: config?.timeoutMs,
             maxBytes: config?.maxBytes,
             tokenType: config?.tokenType,
+            signed: config?.signed,
         });
     }
     /**
@@ -377,6 +474,7 @@ export class EbayApiClient {
             timeoutMs: config?.timeoutMs,
             maxBytes: config?.maxBytes,
             tokenType: config?.tokenType,
+            signed: config?.signed,
         });
     }
     /**
@@ -399,6 +497,7 @@ export class EbayApiClient {
             timeoutMs: config?.timeoutMs,
             maxBytes: config?.maxBytes,
             tokenType: config?.tokenType,
+            signed: config?.signed,
         });
     }
     /**
@@ -414,6 +513,7 @@ export class EbayApiClient {
             timeoutMs: config?.timeoutMs,
             maxBytes: config?.maxBytes,
             tokenType: config?.tokenType,
+            signed: config?.signed,
         });
     }
     /**
@@ -437,6 +537,7 @@ export class EbayApiClient {
             timeoutMs: config?.timeoutMs,
             maxBytes: config?.maxBytes,
             tokenType: config?.tokenType,
+            signed: config?.signed,
         });
     }
     /**

package/build/api/client/signEbayRequest.js

@@ -0,0 +1,124 @@
+import { createHash, createPrivateKey, sign } from 'node:crypto';
+/**
+ * eBay Digital Signatures for APIs (RFC 9421 HTTP Message Signatures).
+ *
+ * eBay requires EU- and UK-domiciled sellers to sign calls to the Finances API,
+ * Fulfillment `issueRefund`, Trading `GetAccount`, and several Post-Order refund
+ * and cancellation calls. A signed request carries four extra headers:
+ *
+ * - `x-ebay-signature-key` — the JWE returned by Key Management `createSigningKey`
+ * - `Content-Digest` — `sha-256=:<base64>:` of the body, only when a body is sent
+ * - `Signature-Input` — the covered components and the `created` timestamp
+ * - `Signature` — the Ed25519 or RSA (PKCS#1 v1.5, SHA-256) signature over the signature base
+ *
+ * @see https://developer.ebay.com/develop/guides/digital-signatures-for-apis
+ * @see https://www.rfc-editor.org/rfc/rfc9421
+ */
+/** Label used for the single signature eBay expects. */
+const SIGNATURE_LABEL = 'sig1';
+/** Header name eBay reads the signing key JWE from. */
+const SIGNATURE_KEY_HEADER = 'x-ebay-signature-key';
+const PEM_PATTERN = /-----BEGIN [A-Z ]*PRIVATE KEY-----/;
+/**
+ * Sign the signature base with Ed25519, or RSASSA-PKCS1-v1_5 with SHA-256.
+ */
+const signBase = (signatureBase, key) => {
+    const signatureBaseBytes = Buffer.from(signatureBase, 'utf8');
+    const digest = key.asymmetricKeyType === 'ed25519' ? null : 'sha256';
+    return sign(digest, signatureBaseBytes, key).toString('base64');
+};
+/** Lower-cased `@authority`: host plus any non-default port (`URL.host` already omits defaults). */
+const authorityOf = (url) => url.host.toLowerCase();
+/** Raised when the configured signing private key cannot be used. */
+export class EbaySigningKeyError extends Error {
+    name = 'EbaySigningKeyError';
+}
+/**
+ * Parse the configured private key into a Node `KeyObject`.
+ *
+ * eBay's `createSigningKey` returns the private key as base64-encoded PKCS#8 DER
+ * without PEM armour; a PEM block (PKCS#8 or PKCS#1 RSA) is accepted as well so
+ * keys converted with openssl keep working. Escaped `\n` sequences — common when a
+ * PEM key is pasted into a single-line env var or JSON config — are unescaped first.
+ *
+ * @param privateKey - Base64 PKCS#8 DER or PEM private key.
+ * @returns The parsed key object.
+ * @throws {EbaySigningKeyError} When the key cannot be parsed or is not Ed25519/RSA.
+ */
+export const parseSigningPrivateKey = (privateKey) => {
+    const trimmed = privateKey.trim().replaceAll('\\n', '\n');
+    let key;
+    try {
+        key = PEM_PATTERN.test(trimmed)
+            ? createPrivateKey(trimmed)
+            : createPrivateKey({
+                key: Buffer.from(trimmed.replaceAll(/\s/g, ''), 'base64'),
+                format: 'der',
+                type: 'pkcs8',
+            });
+    }
+    catch (cause) {
+        throw new EbaySigningKeyError('EBAY_SIGNING_PRIVATE_KEY could not be parsed. Use the privateKey value returned by ebay_create_signing_key (base64 PKCS#8) or a PEM private key.', { cause });
+    }
+    if (key.asymmetricKeyType !== 'ed25519' && key.asymmetricKeyType !== 'rsa') {
+        throw new EbaySigningKeyError(`EBAY_SIGNING_PRIVATE_KEY is a ${key.asymmetricKeyType ?? 'unknown'} key; eBay digital signatures accept only ED25519 or RSA keys.`);
+    }
+    return key;
+};
+/**
+ * Compute the RFC 9530 `Content-Digest` header value for a body.
+ *
+ * @param bodyBytes - Exact body bytes (strings are encoded as UTF-8).
+ * @returns The header value, e.g. `sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=:`.
+ */
+export const computeContentDigest = (bodyBytes) => `sha-256=:${createHash('sha256').update(bodyBytes).digest('base64')}:`;
+/**
+ * Build the RFC 9421 signature base for the components eBay covers.
+ *
+ * @param components - Ordered `[name, value]` pairs of covered components.
+ * @param signatureParams - The serialized inner list and parameters, e.g.
+ *   `("x-ebay-signature-key" "@method" "@path" "@authority");created=1658440308`.
+ * @returns The newline-joined signature base.
+ */
+export const buildSignatureBase = (components, signatureParams) => [
+    ...components.map(([name, value]) => `"${name}": ${value}`),
+    `"@signature-params": ${signatureParams}`,
+].join('\n');
+/**
+ * Produce the eBay digital-signature headers for one request attempt.
+ *
+ * The signature covers `content-digest` (only when a body is present),
+ * `x-ebay-signature-key`, `@method`, `@path`, and `@authority`, matching eBay's
+ * documented `Signature-Input`. Call this once per attempt so retries carry a
+ * fresh `created` timestamp.
+ *
+ * @param request - Method, the URL eBay receives, and the exact body bytes.
+ * @param jwe - The `jwe` value from `createSigningKey`, sent in `x-ebay-signature-key`.
+ * @param key - Parsed private key (see {@link parseSigningPrivateKey}).
+ * @param now - Clock override in milliseconds, for tests.
+ * @returns Headers to merge into the outgoing request.
+ *
+ * @example
+ * ```ts
+ * const key = parseSigningPrivateKey(privateKey);
+ * const headers = signEbayRequest({ method: 'GET', url }, jwe, key);
+ * ```
+ */
+export const signEbayRequest = (request, jwe, key, now = Date.now()) => {
+    const url = new URL(request.url);
+    const created = Math.floor(now / 1000);
+    const headers = { [SIGNATURE_KEY_HEADER]: jwe };
+    const components = [];
+    if (request.bodyBytes !== undefined) {
+        const contentDigest = computeContentDigest(request.bodyBytes);
+        headers['Content-Digest'] = contentDigest;
+        components.push(['content-digest', contentDigest]);
+    }
+    components.push([SIGNATURE_KEY_HEADER, jwe], ['@method', request.method.toUpperCase()], ['@path', url.pathname], ['@authority', authorityOf(url)]);
+    const signatureParams = `(${components.map(([name]) => `"${name}"`).join(' ')});created=${created}`;
+    const signatureBase = buildSignatureBase(components, signatureParams);
+    const signature = signBase(signatureBase, key);
+    headers['Signature-Input'] = `${SIGNATURE_LABEL}=${signatureParams}`;
+    headers.Signature = `${SIGNATURE_LABEL}=:${signature}:`;
+    return headers;
+};

package/build/api/communication/feedback.js

@@ -19,13 +19,13 @@ export class FeedbackApi {
      * @example
      * ```ts
      * const awaiting = await Effect.runPromise(
-     *   feedbackApi.getAwaitingFeedback({ filter: 'userRole:SELLER', limit: 25 }),
+     *   feedbackApi.getItemsAwaitingFeedback({ filter: 'userRole:SELLER', limit: 25 }),
      * );
      * ```
      *
      * @see https://developer.ebay.com/api-docs/commerce/feedback/resources/awaiting_feedback/methods/getItemsAwaitingFeedback
      */
-    getAwaitingFeedback = (input = {}) => {
+    getItemsAwaitingFeedback = (input = {}) => {
         const client = this.client;
         const path = `${this.basePath}/awaiting_feedback`;
         return Effect.gen(function* () {
@@ -128,13 +128,13 @@ export class FeedbackApi {
      * @example
      * ```ts
      * const feedback = await Effect.runPromise(
-     *   feedbackApi.leaveFeedbackForBuyer({ commentText: 'Great buyer', commentType: 'POSITIVE' }),
+     *   feedbackApi.leaveFeedback({ commentText: 'Great buyer', commentType: 'POSITIVE' }),
      * );
      * ```
      *
      * @see https://developer.ebay.com/api-docs/commerce/feedback/resources/feedback/methods/leaveFeedback
      */
-    leaveFeedbackForBuyer = (feedbackData) => {
+    leaveFeedback = (feedbackData) => {
         const client = this.client;
         const path = `${this.basePath}/feedback`;
         return Effect.gen(function* () {