ebay-mcp 1.13.2 → 1.14.0

package/build/tools/contracts.js

@@ -1,26 +1,36 @@
 import { getToolEntries } from '../tools/registry.js';
-function isJsonObject(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-/** Builds public tool contracts from the validated tool registry entries. */
-export function getToolContracts() {
-    return getToolEntries().map(({ definition }) => ({
-        annotations: definition.annotations,
-        description: definition.description,
-        name: definition.name,
-        inputSchema: definition.inputSchema,
-        outputSchema: definition.outputSchema,
-        title: definition.title,
-    }));
-}
-function isZodLikeSchema(schema) {
-    return (typeof schema === 'object' &&
-        schema !== null &&
-        'safeParse' in schema &&
-        typeof schema.safeParse === 'function');
-}
-/** Validates tool contracts for unique names, descriptions, input schemas, and output schemas. */
-export function validateToolContracts(contracts = getToolContracts()) {
+import { isEffectBackedSchema } from '../utils/effectSchema.js';
+const isJsonObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/**
+ * Builds public tool contracts from the validated tool registry entries.
+ *
+ * @returns Normalized tool contracts in registry execution order.
+ *
+ * @example
+ * ```ts
+ * const contracts = getToolContracts();
+ * ```
+ */
+export const getToolContracts = () => getToolEntries().map(({ definition }) => ({
+    annotations: definition.annotations,
+    description: definition.description,
+    name: definition.name,
+    inputSchema: definition.inputSchema,
+    outputSchema: definition.outputSchema,
+    title: definition.title,
+}));
+/**
+ * Validates tool contracts for unique names, descriptions, input schemas, and output schemas.
+ *
+ * @param contracts - Contracts to validate, defaulting to the current registry projection.
+ * @returns Duplicate names and malformed contract fields grouped by failure type.
+ *
+ * @example
+ * ```ts
+ * const validation = validateToolContracts(getToolContracts());
+ * ```
+ */
+export const validateToolContracts = (contracts = getToolContracts()) => {
     const seenNames = new Set();
     const duplicateContracts = new Set();
     const invalidInputSchemaFields = [];
@@ -37,7 +47,7 @@ export function validateToolContracts(contracts = getToolContracts()) {
         }
         else {
             for (const [fieldName, schema] of Object.entries(contract.inputSchema)) {
-                if (!isZodLikeSchema(schema)) {
+                if (!isEffectBackedSchema(schema)) {
                     invalidInputSchemaFields.push(`${contract.name}.${fieldName}`);
                 }
             }
@@ -66,4 +76,4 @@ export function validateToolContracts(contracts = getToolContracts()) {
         missingDescriptions: missingDescriptions.sort(),
         missingInputSchemas: missingInputSchemas.sort(),
     };
-}
+};

package/build/tools/{define-tool.js → defineTool.js}

@@ -1,5 +1,5 @@
-import { z } from 'zod';
 import { uiArchetypes } from '../tools/ui/archetypes.js';
+import { decodeEffectSchemaSync, z } from '../utils/effectSchema.js';
 /**
  * Erases the compile-time result type from a {@link ToolUiSpec} so the binding can
  * live on the non-generic {@link ToolEntry}, and resolves the archetype's
@@ -16,28 +16,7 @@ function resolveToolUi(ui) {
         map: (result) => ui.map(result),
     };
 }
-/**
- * Binds a tool's Zod input shape to its handler so the shape is the single
- * source of truth for both the advertised MCP schema and the handler's
- * compile-time argument types.
- *
- * The returned {@link ToolEntry} carries a `ToolHandler` that validates raw
- * arguments against the shape before delegating, which gives the codebase two
- * properties it lacked while definitions and handlers lived in separate trees
- * joined by a string key:
- *
- *  - **Drift is a compile error.** The handler can only read fields the shape
- *    declares, with their declared types — a renamed field or changed type fails
- *    `tsc` instead of surfacing at runtime, and the per-handler `as` casts
- *    disappear.
- *  - **One validation path.** Both the MCP SDK transport and the registry's
- *    `executeTool` (used by tests) run the same parse, so tests exercise the
- *    validation production actually performs.
- *
- * Re-validating on the SDK path (which already parsed the args) is intentional
- * and cheap: the input schemas contain no `.transform()` or async refinements,
- * so the second parse is idempotent.
- */
+/** Builds the public MCP definition from the richer tool spec. */
 function toDefinition(spec) {
     return {
         name: spec.name,
@@ -49,18 +28,41 @@ function toDefinition(spec) {
         _meta: spec._meta,
     };
 }
-export function defineTool(spec) {
+/**
+ * Binds a tool's Effect-backed input shape to its handler so the shape is the single
+ * source of truth for both the advertised MCP schema and the handler's
+ * compile-time argument types.
+ *
+ * The returned {@link ToolEntry} carries a `ToolHandler` that validates raw
+ * arguments against the Effect schema before delegating. Re-validating on the
+ * SDK path is intentional and cheap: input schemas contain no async refinements,
+ * so the second decode is idempotent.
+ *
+ * @param spec - Tool definition, input schema, handler, and optional UI projection.
+ * @returns A registry entry whose handler validates args from the schema before execution.
+ *
+ * @example
+ * ```ts
+ * const entry = defineTool({
+ *   name: 'ebay_get_custom_policies',
+ *   description: 'Retrieve custom policies defined for the seller account',
+ *   inputSchema: getCustomPoliciesInputSchema.shape,
+ *   handler: (api, args) => Effect.runPromise(api.account.getCustomPolicies(args)),
+ * });
+ * ```
+ */
+export const defineTool = (spec) => {
     const schema = z.object(spec.inputSchema);
-    // Non-async: `schema.parse` runs synchronously so invalid input rejects via
+    // Non-async: Effect decode runs synchronously so invalid input rejects via
     // the caller's `await`, and the handler's returned promise passes straight
     // through without an extra await layer.
-    const handler = (api, args) => spec.handler(api, schema.parse(args));
+    const handler = (api, args) => spec.handler(api, decodeEffectSchemaSync(schema, args));
     return {
         definition: toDefinition(spec),
         handler,
         ui: spec.ui ? resolveToolUi(spec.ui) : undefined,
     };
-}
+};
 /**
  * Like {@link defineTool}, but invokes the handler with the raw transport
  * arguments WITHOUT re-validating them against `inputSchema`.
@@ -75,12 +77,25 @@ export function defineTool(spec) {
  *
  * `args` is typed from the shape for handler ergonomics, but the values are not
  * validated by this factory — the handler is responsible for that.
+ *
+ * @param spec - Tool definition, advertised input schema, raw handler, and optional UI projection.
+ * @returns A registry entry whose handler receives raw transport args.
+ *
+ * @example
+ * ```ts
+ * const entry = rawTool({
+ *   name: 'ebay_send_message',
+ *   description: 'Send a member message',
+ *   inputSchema: advertisedMessageShape,
+ *   handler: (api, args) => api.message.sendMessage(args),
+ * });
+ * ```
  */
-export function rawTool(spec) {
+export const rawTool = (spec) => {
     const handler = (api, args) => spec.handler(api, args);
     return {
         definition: toDefinition(spec),
         handler,
         ui: spec.ui ? resolveToolUi(spec.ui) : undefined,
     };
-}
+};

package/build/tools/registry.js

@@ -1,12 +1,25 @@
-import { handlerOnlyEntries, registeredEntries } from '../tools/categories/index.js';
-/** Handler lookup keyed by tool name, including handler-only (unadvertised) tools. */
-const handlerByName = Object.fromEntries([...registeredEntries, ...handlerOnlyEntries].map((entry) => [
-    entry.definition.name,
-    entry.handler,
-]));
+import { registeredEntries } from '../tools/categories/index.js';
+import { Data, Effect } from 'effect';
+/** Tagged failure returned when the tool registry cannot resolve a runnable tool. */
+export class ToolRegistryError extends Data.TaggedError('ToolRegistryError') {
+}
+/** Handler lookup keyed by registered public tool name. */
+const handlerByName = Object.fromEntries(registeredEntries.map((entry) => [entry.definition.name, entry.handler]));
 let cachedEntries;
-/** Validates that tool definitions have unique names and matching handlers. */
-export function validateToolRegistry(definitions = registeredEntries.map((entry) => entry.definition), handlers = handlerByName) {
+/**
+ * Validates that tool definitions have unique names and matching handlers.
+ *
+ * @param definitions - Public tool definitions to validate, defaulting to registered tools.
+ * @param handlers - Handler lookup used to verify every definition can execute.
+ * @returns Duplicate definition names plus missing or orphaned handlers.
+ *
+ * @example
+ * ```ts
+ * const validation = validateToolRegistry();
+ * const hasDuplicates = validation.duplicateToolNames.length > 0;
+ * ```
+ */
+export const validateToolRegistry = (definitions = registeredEntries.map((entry) => entry.definition), handlers = handlerByName) => {
     const seenNames = new Set();
     const duplicateNames = new Set();
     for (const definition of definitions) {
@@ -24,8 +37,8 @@ export function validateToolRegistry(definitions = registeredEntries.map((entry)
             .sort(),
         orphanHandlers: [...handlerNames].filter((name) => !seenNames.has(name)).sort(),
     };
-}
-function assertRunnableRegistry() {
+};
+const validateRunnableRegistry = () => {
     const validation = validateToolRegistry();
     const failures = [
         validation.duplicateToolNames.length > 0
@@ -36,31 +49,76 @@ function assertRunnableRegistry() {
             : undefined,
     ].filter(Boolean);
     if (failures.length > 0) {
-        throw new Error(`Invalid tool registry: ${failures.join('; ')}`);
+        return Effect.fail(new ToolRegistryError({
+            message: `Invalid tool registry: ${failures.join('; ')}`,
+        }));
     }
-}
-/** Returns cached runnable registry entries after validating definitions and handlers. */
-export function getToolEntries() {
+    return Effect.void;
+};
+/**
+ * Returns cached runnable registry entries after validating definitions and handlers.
+ *
+ * @returns Registered tool entries in execution order.
+ *
+ * @example
+ * ```ts
+ * const entries = getToolEntries();
+ * ```
+ */
+export const getToolEntries = () => {
     if (cachedEntries) {
         return cachedEntries;
     }
-    assertRunnableRegistry();
+    Effect.runSync(validateRunnableRegistry());
     cachedEntries = registeredEntries;
     return cachedEntries;
-}
-/** Returns public tool definitions in registry execution order. */
-export function getToolDefinitions() {
-    return getToolEntries().map((entry) => entry.definition);
-}
-/** Looks up the handler registered for a tool name, if one exists. */
-export function getToolHandler(toolName) {
-    return handlerByName[toolName];
-}
-/** Executes a registered tool handler or throws when the tool name is unknown. */
-export async function executeTool(api, toolName, args) {
+};
+/**
+ * Returns public tool definitions in registry execution order.
+ *
+ * @returns MCP tool definitions advertised to clients.
+ *
+ * @example
+ * ```ts
+ * const definitions = getToolDefinitions();
+ * ```
+ */
+export const getToolDefinitions = () => getToolEntries().map((entry) => entry.definition);
+/**
+ * Looks up the handler registered for a tool name, if one exists.
+ *
+ * @param toolName - MCP tool name to resolve.
+ * @returns The registered handler, or undefined when the name is unknown.
+ *
+ * @example
+ * ```ts
+ * const handler = getToolHandler('ebay_get_custom_policies');
+ * ```
+ */
+export const getToolHandler = (toolName) => handlerByName[toolName];
+/**
+ * Executes a registered tool handler and rejects when the tool name is unknown.
+ *
+ * @param api - eBay API facade passed to the selected tool handler.
+ * @param toolName - MCP tool name to execute.
+ * @param args - Raw transport arguments parsed by the selected tool entry.
+ * @returns The selected handler's result.
+ *
+ * @example
+ * ```ts
+ * const result = await executeTool(api, 'ebay_get_custom_policies', {});
+ * ```
+ */
+export const executeTool = async (api, toolName, args) => Effect.runPromise(Effect.gen(function* () {
     const handler = getToolHandler(toolName);
     if (!handler) {
-        throw new Error(`Unknown tool: ${toolName}`);
+        return yield* Effect.fail(new ToolRegistryError({
+            message: `Unknown tool: ${toolName}`,
+            toolName,
+        }));
     }
-    return await handler(api, args);
-}
+    return yield* Effect.tryPromise({
+        try: () => Promise.resolve(handler(api, args)),
+        catch: (error) => error,
+    });
+}));

package/build/tools/schemas.js

@@ -1,7 +1,7 @@
-import { z } from 'zod';
-import { TimeDurationUnit, RegionType, ShippingCostType, ShippingOptionType, DepositType, RefundMethod, ReturnMethod, ReturnShippingCostPayer, Condition, LengthUnit, WeightUnit, PricingVisibility, FormatType, LocationType, MerchantLocationStatus, DayOfWeek, ReasonForRefund, FundingModel, MessageReferenceType, FeedbackRating, ReportedItemType, } from '../types/ebay-enums.js';
+import { z } from '../utils/effectSchema.js';
+import { TimeDurationUnit, RegionType, ShippingCostType, ShippingOptionType, DepositType, RefundMethod, ReturnMethod, ReturnShippingCostPayer, Condition, LengthUnit, WeightUnit, PricingVisibility, FormatType, LocationType, MerchantLocationStatus, DayOfWeek, ReasonForRefund, FundingModel, MessageReferenceType, FeedbackRating, ReportedItemType, } from '../types/ebayEnums.js';
 /**
- * Reusable Zod schemas for eBay API tool input validation
+ * Reusable Effect-backed schemas for eBay API tool input validation
  *
  * These schemas provide type-safe validation while remaining flexible
  * enough to accept the full complexity of eBay API request objects.
@@ -556,60 +556,6 @@ export const infringementDataSchema = z
     comments: z.string().optional(),
 })
     .passthrough();
-// VERO API schemas
-/** VeRO report payload for intellectual-property violation submissions. */
-export const veroReportDataSchema = z
-    .object({
-    items: z.array(z.object({
-        itemId: z.string(),
-        reportingReason: z.string(),
-    })),
-    rightsOwnerEmail: z.string().email().optional(),
-    message: z.string().optional(),
-})
-    .passthrough();
-/** Shipping quote request payload for estimated shipping rates. */
-export const shippingQuoteRequestSchema = z
-    .object({
-    packageDetails: z
-        .object({
-        weight: z
-            .object({
-            value: z.number(),
-            unit: z.string(),
-        })
-            .passthrough(),
-        dimensions: z
-            .object({
-            height: z.number().optional(),
-            length: z.number().optional(),
-            width: z.number().optional(),
-            unit: z.string().optional(),
-        })
-            .passthrough()
-            .optional(),
-    })
-        .passthrough(),
-    shipFrom: z
-        .object({
-        addressLine1: z.string().optional(),
-        city: z.string().optional(),
-        stateOrProvince: z.string().optional(),
-        postalCode: z.string().optional(),
-        country: z.string(),
-    })
-        .passthrough(),
-    shipTo: z
-        .object({
-        addressLine1: z.string().optional(),
-        city: z.string().optional(),
-        stateOrProvince: z.string().optional(),
-        postalCode: z.string().optional(),
-        country: z.string(),
-    })
-        .passthrough(),
-})
-    .passthrough();
 // ============================================================================
 // Bulk Operation Schemas
 // ============================================================================

package/build/tools/ui/archetypes.js

@@ -8,4 +8,5 @@ export const uiArchetypes = {
     table: { uri: 'ui://ebay/table.html', name: 'eBay table view', htmlFile: 'table.html' },
     card: { uri: 'ui://ebay/card.html', name: 'eBay detail card view', htmlFile: 'card.html' },
     chart: { uri: 'ui://ebay/chart.html', name: 'eBay chart view', htmlFile: 'chart.html' },
+    stat: { uri: 'ui://ebay/stat.html', name: 'eBay stat grid view', htmlFile: 'stat.html' },
 };

package/build/tools/ui/{map-helpers.js → mapHelpers.js}

@@ -12,35 +12,59 @@
  * Renders an eBay money object as `"<value> <currency>"` (e.g. `"25.99 USD"`),
  * or just the value when no currency is present. Returns `null` for a missing
  * amount so callers can drop it straight into a nullable cell or field.
+ *
+ * @param amount - eBay amount-like object from a generated response.
+ * @returns A display string with currency, or null when the amount is missing.
+ *
+ * @example
+ * ```ts
+ * formatAmount({ value: '25.99', currency: 'USD' });
+ * ```
  */
-export function formatAmount(amount) {
+export const formatAmount = (amount) => {
     if (amount?.value == null) {
         return null;
     }
     return amount.currency ? `${amount.value} ${amount.currency}` : amount.value;
-}
+};
 /**
  * Turns eBay's `SCREAMING_SNAKE_CASE` status codes into human-readable sentence
  * case (`"ITEM_NOT_RECEIVED"` → `"Item not received"`): underscores become
  * spaces and only the first word is capitalised, which reads more naturally for
- * multi-word statuses than Title Case. Returns an em dash for a missing status
- * so tables and cards never render a blank cell.
+ * multi-word statuses than Title Case. Returns `null` for a missing status so
+ * the React view, not the mapper, owns placeholder rendering.
+ *
+ * @param status - Optional eBay enum/status value.
+ * @returns A display label, or null when no status was provided.
+ *
+ * @example
+ * ```ts
+ * humanizeStatus('ITEM_NOT_RECEIVED');
+ * ```
  */
-export function humanizeStatus(status) {
+export const humanizeStatus = (status) => {
     if (!status) {
-        return '—';
+        return null;
     }
     const lowered = status.toLowerCase().replace(/_/g, ' ');
     return lowered.charAt(0).toUpperCase() + lowered.slice(1);
-}
+};
 /**
  * Maps a status code to a {@link CardBadge} tone so detail cards can colour
  * their state pills. Unknown or terminal-neutral statuses fall back to
  * `'neutral'`. The buckets are intentionally broad keyword matches rather than
  * an exhaustive enum — new eBay statuses degrade to neutral, never to a wrong
  * colour-implied meaning.
+ *
+ * @param status - Optional eBay enum/status value.
+ * @returns Badge tone used by card view models.
+ *
+ * @example
+ * ```ts
+ * statusTone('FULFILLED');
+ * ```
  */
-export function statusTone(status) {
+export const statusTone = (status) => {
     if (!status) {
         return 'neutral';
     }
@@ -55,27 +79,44 @@ export function statusTone(status) {
         return 'success';
     }
     return 'neutral';
-}
+};
 /**
  * Coerces an untyped JSON leaf (the analytics specs type report values as
  * `Record<string, never>`, though at runtime they are numbers or numeric
- * strings) to a finite number, defaulting to `0`. Used for chart Y values.
+ * strings) to a finite number. Missing or invalid values return `null` so chart
+ * mappers can omit the point instead of inventing a zero.
+ *
+ * @param value - Analytics value leaf from an eBay report response.
+ * @returns A finite number for chart points, or null for non-numeric input.
+ *
+ * @example
+ * ```ts
+ * toNumber('42');
+ * ```
  */
-export function toNumber(value) {
+export const toNumber = (value) => {
     if (typeof value === 'number') {
-        return Number.isFinite(value) ? value : 0;
+        return Number.isFinite(value) ? value : null;
     }
     if (typeof value === 'string') {
         const parsed = Number(value);
-        return Number.isFinite(parsed) ? parsed : 0;
+        return Number.isFinite(parsed) ? parsed : null;
     }
-    return 0;
-}
+    return null;
+};
 /**
  * Coerces an untyped JSON leaf to a chart-axis label string, returning `''` for
  * values that have no sensible textual form (objects, `null`, `undefined`).
+ *
+ * @param value - Analytics dimension leaf from an eBay report response.
+ * @returns A primitive label string, or an empty string when no label is available.
+ *
+ * @example
+ * ```ts
+ * toLabel(7);
+ * ```
  */
-export function toLabel(value) {
+export const toLabel = (value) => {
     if (typeof value === 'string') {
         return value;
     }
@@ -83,15 +124,24 @@ export function toLabel(value) {
         return String(value);
     }
     return '';
-}
+};
 /**
  * Shortens free-text (product descriptions, titles) to `max` characters with a
  * trailing ellipsis, so a table cell or card field stays one line. Returns `''`
  * for missing text.
+ *
+ * @param text - Optional free-text value from an eBay response.
+ * @param max - Maximum display length including the ellipsis.
+ * @returns Truncated text, original text, or an empty string when text is missing.
+ *
+ * @example
+ * ```ts
+ * truncate('A long product title', 12);
+ * ```
  */
-export function truncate(text, max = 80) {
+export const truncate = (text, max = 80) => {
     if (!text) {
         return '';
     }
     return text.length > max ? `${text.slice(0, max - 1)}…` : text;
-}
+};