@lehaotech/walmart-mcp 0.5.4

package/build/tools/index.js

@@ -0,0 +1,379 @@
+import { upsertEnvVars } from '../utils/env-file.js';
+import { tokenManagementTools } from './definitions/token-management.js';
+import { itemTools } from './definitions/items.js';
+import { inventoryTools } from './definitions/inventory.js';
+import { orderTools } from './definitions/orders.js';
+import { pricingTools } from './definitions/pricing.js';
+import { feedTools } from './definitions/feeds.js';
+import { fulfillmentTools } from './definitions/fulfillment.js';
+import { returnTools } from './definitions/returns.js';
+import { reportTools } from './definitions/reports.js';
+import { notificationTools } from './definitions/notifications.js';
+import { advertisingTools } from './definitions/advertising.js';
+import { settingsTools } from './definitions/settings.js';
+import { discoveryTools } from './definitions/discovery.js';
+import { searchEndpoints } from '../utils/endpoint-catalog.js';
+export function getToolDefinitions() {
+    return [
+        ...tokenManagementTools,
+        ...itemTools,
+        ...inventoryTools,
+        ...orderTools,
+        ...pricingTools,
+        ...feedTools,
+        ...fulfillmentTools,
+        ...returnTools,
+        ...reportTools,
+        ...notificationTools,
+        ...advertisingTools,
+        ...settingsTools,
+        ...discoveryTools,
+    ];
+}
+export async function executeTool(api, toolName, args) {
+    switch (toolName) {
+        // ===== Token Management =====
+        case 'walmart_get_token':
+            await api.auth.refreshToken();
+            return api.auth.getTokenInfo();
+        case 'walmart_get_token_status':
+            return await api.auth.getTokenDetail();
+        case 'walmart_get_token_info':
+            return api.auth.getTokenInfo();
+        case 'walmart_set_credentials': {
+            upsertEnvVars({
+                WALMART_CLIENT_ID: args.clientId,
+                WALMART_CLIENT_SECRET: args.clientSecret,
+            });
+            return { success: true, message: 'Credentials saved to .env. Restart the server to apply.' };
+        }
+        case 'walmart_display_credentials':
+            return {
+                clientId: process.env.WALMART_CLIENT_ID || '(not set)',
+                clientSecret: process.env.WALMART_CLIENT_SECRET
+                    ? `${process.env.WALMART_CLIENT_SECRET.substring(0, 8)}...${process.env.WALMART_CLIENT_SECRET.slice(-4)}`
+                    : '(not set)',
+                environment: process.env.WALMART_ENVIRONMENT || 'sandbox',
+                market: process.env.WALMART_MARKET || 'us',
+                svcName: process.env.WALMART_SVC_NAME || 'Walmart Marketplace',
+            };
+        case 'walmart_setup_guide': {
+            const hasMarketplaceCreds = !!(process.env.WALMART_CLIENT_ID && process.env.WALMART_CLIENT_SECRET);
+            const hasAdCreds = !!(process.env.WALMART_AD_CONSUMER_ID && process.env.WALMART_AD_PRIVATE_KEY);
+            const environment = process.env.WALMART_ENVIRONMENT || 'sandbox';
+            return {
+                status: hasMarketplaceCreds ? 'ready' : 'credentials_required',
+                configured: {
+                    marketplaceCredentials: hasMarketplaceCreds,
+                    advertisingCredentials: hasAdCreds,
+                    environment,
+                    market: process.env.WALMART_MARKET || 'us',
+                },
+                steps: [
+                    '1. Get API credentials: sign in at https://developer.walmart.com/, create an app under Marketplace, and copy the Client ID and Client Secret.',
+                    '2. Provide credentials one of two ways: (a) set WALMART_CLIENT_ID and WALMART_CLIENT_SECRET in your MCP server "env" (or a .env file in the project root) and restart, or (b) call the walmart_set_credentials tool now with your Client ID and Secret.',
+                    '3. Choose the environment: set WALMART_ENVIRONMENT to "sandbox" (default, for testing) or "production" (for live selling).',
+                    '4. Verify: call walmart_get_token to confirm authentication works, then walmart_display_credentials to review the active configuration.',
+                    '5. (Optional) For Walmart Connect advertising tools, also set WALMART_AD_CONSUMER_ID and WALMART_AD_PRIVATE_KEY (apply at https://www.walmartconnect.com/).',
+                ],
+                nextAction: hasMarketplaceCreds
+                    ? 'Credentials are set. Call walmart_get_token to verify, then use any tool.'
+                    : 'No marketplace credentials yet. Call walmart_set_credentials, or set the env vars and restart.',
+                docs: 'https://developer.walmart.com/',
+            };
+        }
+        case 'walmart_get_rate_budget': {
+            const status = api.getRateLimiterStatus();
+            return {
+                ...status,
+                notes: [
+                    'localRemaining = requests this MCP can issue right now under the sliding-window limiter.',
+                    'serverTokensRemaining = most recent x-current-token-count from Walmart (null if no API call has been made yet).',
+                    'serverReplenishTime = most recent x-next-replenish-time (ISO 8601) — when Walmart will top your bucket back up.',
+                    'Walmart Marketplace does not have an OAuth user-token flow; rate limits depend on your seller-account tier.',
+                ],
+            };
+        }
+        // ===== Items =====
+        case 'walmart_get_all_items':
+            return await api.items.getAllItems(args);
+        case 'walmart_get_item':
+            return await api.items.getItem(args.sku);
+        case 'walmart_retire_item':
+            return await api.items.retireItem(args.sku);
+        case 'walmart_bulk_retire_items':
+            return await api.items.bulkRetireItems(args.skus);
+        case 'walmart_get_item_count':
+            return await api.items.getItemCount(args);
+        case 'walmart_get_taxonomy':
+            return await api.items.getTaxonomy();
+        case 'walmart_get_item_spec':
+            return await api.items.getItemSpec(args);
+        case 'walmart_submit_item_feed':
+            return await api.items.submitItemFeed(args.feedData);
+        case 'walmart_submit_item_update_feed':
+            return await api.items.submitItemUpdateFeed(args.feedData);
+        case 'walmart_submit_wfs_item_feed':
+            return await api.items.submitWfsItemFeed(args.feedData);
+        case 'walmart_convert_to_wfs':
+            return await api.items.convertToWfs(args.feedData);
+        case 'walmart_get_hazmat_items':
+            return await api.items.getHazmatItems(args.requestData);
+        // ===== Inventory =====
+        case 'walmart_get_inventory':
+            return await api.inventory.getInventory(args.sku);
+        case 'walmart_update_inventory':
+            return await api.inventory.updateInventory(args);
+        case 'walmart_get_inventory_all_nodes':
+            return await api.inventory.getInventoryAllNodes(args.sku);
+        case 'walmart_update_inventory_multi_node':
+            return await api.inventory.updateInventoryMultiNode(args.sku, args.inventoryData);
+        case 'walmart_get_all_inventory':
+            return await api.inventory.getAllInventory(args);
+        case 'walmart_submit_inventory_feed':
+            return await api.inventory.submitInventoryFeed(args.feedData);
+        case 'walmart_submit_multi_node_inventory_feed':
+            return await api.inventory.submitMultiNodeInventoryFeed(args.feedData);
+        case 'walmart_get_lag_time':
+            return await api.inventory.getLagTime(args.sku);
+        case 'walmart_update_lag_time':
+            return await api.inventory.updateLagTime(args);
+        case 'walmart_submit_lagtime_feed':
+            return await api.inventory.submitLagTimeFeed(args.feedData);
+        // ===== Orders =====
+        case 'walmart_get_all_orders':
+            return await api.orders.getAllOrders(args);
+        case 'walmart_get_released_orders':
+            return await api.orders.getReleasedOrders(args);
+        case 'walmart_get_order':
+            return await api.orders.getOrder(args.purchaseOrderId);
+        case 'walmart_acknowledge_order':
+            return await api.orders.acknowledgeOrder(args.purchaseOrderId);
+        case 'walmart_ship_order':
+            return await api.orders.shipOrder(args.purchaseOrderId, args.shipmentData);
+        case 'walmart_cancel_order':
+            return await api.orders.cancelOrder(args.purchaseOrderId, args.cancelData);
+        case 'walmart_refund_order':
+            return await api.orders.refundOrder(args.purchaseOrderId, args.refundData);
+        case 'walmart_get_shipping_carriers':
+            return await api.orders.getShippingCarriers();
+        case 'walmart_create_shipping_label':
+            return await api.orders.createShippingLabel(args.labelData);
+        case 'walmart_get_shipping_estimate':
+            return await api.orders.getShippingEstimate(args.estimateParams);
+        // ===== Pricing =====
+        case 'walmart_update_price':
+            return await api.pricing.updatePrice(args);
+        case 'walmart_submit_price_feed':
+            return await api.pricing.submitPriceFeed(args.feedData);
+        case 'walmart_submit_mp_price_feed':
+            return await api.pricing.submitMpPriceFeed(args.feedData);
+        case 'walmart_submit_promo_price_feed':
+            return await api.pricing.submitPromoPriceFeed(args.feedData);
+        case 'walmart_get_repricer_strategies':
+            return await api.pricing.getRepricerStrategies();
+        case 'walmart_create_repricer_strategy':
+            return await api.pricing.createRepricerStrategy(args.strategyData);
+        case 'walmart_update_repricer_strategy':
+            return await api.pricing.updateRepricerStrategy(args.strategyData);
+        case 'walmart_delete_repricer_strategy':
+            return await api.pricing.deleteRepricerStrategy(args.strategyId);
+        case 'walmart_assign_items_to_strategy':
+            return await api.pricing.assignItemsToStrategy(args);
+        case 'walmart_unassign_items_from_strategy':
+            return await api.pricing.unassignItemsFromStrategy(args);
+        // ===== Feeds =====
+        case 'walmart_get_all_feed_statuses':
+            return await api.feeds.getAllFeedStatuses(args);
+        case 'walmart_get_feed_status':
+            return await api.feeds.getFeedStatus(args.feedId);
+        case 'walmart_get_feed_item_status':
+            return await api.feeds.getFeedItemStatus(args.feedId);
+        case 'walmart_submit_generic_feed':
+            return await api.feeds.submitFeed(args.feedType, args.feedData);
+        case 'walmart_poll_feed_until_complete': {
+            const maxWaitMs = args.maxWaitSeconds
+                ? args.maxWaitSeconds * 1000
+                : undefined;
+            return await api.feeds.pollFeedUntilComplete(args.feedId, maxWaitMs);
+        }
+        // ===== WFS Fulfillment =====
+        case 'walmart_create_inbound_order':
+            return await api.fulfillment.createInboundOrder(args.orderData);
+        case 'walmart_get_inbound_shipments':
+            return await api.fulfillment.getInboundShipments(args);
+        case 'walmart_get_inbound_errors':
+            return await api.fulfillment.getInboundErrors(args);
+        case 'walmart_get_shipment_items':
+            return await api.fulfillment.getShipmentItems(args);
+        case 'walmart_get_shipment_quantities':
+            return await api.fulfillment.getShipmentQuantities(args);
+        case 'walmart_get_shipment_label':
+            return await api.fulfillment.getShipmentLabel(args.shipmentId);
+        case 'walmart_update_shipment_tracking':
+            return await api.fulfillment.updateShipmentTracking(args.trackingData);
+        case 'walmart_cancel_inbound_order':
+            return await api.fulfillment.cancelInboundOrder(args.inboundOrderId);
+        case 'walmart_get_purchased_label':
+            return await api.fulfillment.getShippingLabel(args.purchaseOrderId);
+        case 'walmart_get_label_by_tracking':
+            return await api.fulfillment.getLabelByTracking(args.carrierId, args.trackingNo);
+        case 'walmart_discard_label':
+            return await api.fulfillment.discardLabel(args.labelData);
+        case 'walmart_get_package_types':
+            return await api.fulfillment.getPackageTypes(args.carrierId);
+        case 'walmart_create_mcs_order':
+            return await api.fulfillment.createMcsOrder(args.orderData);
+        case 'walmart_cancel_mcs_order':
+            return await api.fulfillment.cancelMcsOrder(args.cancelData);
+        case 'walmart_get_mcs_order_status':
+            return await api.fulfillment.getMcsOrderStatus(args.orderId);
+        case 'walmart_get_carrier_rate_quotes':
+            return await api.fulfillment.getCarrierRateQuotes(args.quoteData);
+        case 'walmart_book_carrier_shipment':
+            return await api.fulfillment.bookCarrierShipment(args.bookingData);
+        case 'walmart_get_carrier_label':
+            return await api.fulfillment.getCarrierLabel(args.shipmentId);
+        case 'walmart_schedule_carrier_pickup':
+            return await api.fulfillment.scheduleCarrierPickup(args.pickupData);
+        // ===== Returns & Refunds =====
+        case 'walmart_get_all_returns':
+            return await api.returns.getAllReturns(args);
+        case 'walmart_get_return':
+            return await api.returns.getReturn(args.returnOrderId);
+        case 'walmart_approve_return':
+            return await api.returns.approveReturn(args.approvalData);
+        case 'walmart_reject_return':
+            return await api.returns.rejectReturn(args.rejectionData);
+        case 'walmart_issue_return_refund':
+            return await api.returns.issueReturnRefund(args.returnOrderId, args.itemId, args.refundData);
+        case 'walmart_generate_return_label':
+            return await api.returns.generateReturnLabel(args.returnOrderId, args.itemId, args.labelData);
+        case 'walmart_get_wfs_returns':
+            return await api.returns.getWfsReturns(args);
+        case 'walmart_get_return_count':
+            return await api.returns.getReturnCount(args);
+        // ===== Reports & Analytics =====
+        case 'walmart_create_report':
+            return await api.reports.createReport(args.reportData);
+        case 'walmart_get_report_requests':
+            return await api.reports.getReportRequests(args);
+        case 'walmart_get_report_status':
+            return await api.reports.getReportStatus(args.requestId);
+        case 'walmart_download_report':
+            return await api.reports.downloadReport(args);
+        case 'walmart_create_report_schedule':
+            return await api.reports.createReportSchedule(args.scheduleData);
+        case 'walmart_get_report_schedules':
+            return await api.reports.getReportSchedules(args);
+        case 'walmart_update_report_schedule':
+            return await api.reports.updateReportSchedule(args.scheduleId, args.scheduleData);
+        case 'walmart_delete_report_schedule':
+            return await api.reports.deleteReportSchedule(args.scheduleId);
+        case 'walmart_get_unpublished_items':
+            return await api.reports.getUnpublishedItems(args);
+        case 'walmart_get_listing_quality':
+            return await api.reports.getListingQuality(args);
+        case 'walmart_get_quality_categories':
+            return await api.reports.getQualityCategories(args);
+        case 'walmart_get_item_quality_details':
+            return await api.reports.getItemQualityDetails(args);
+        // ===== Notifications =====
+        case 'walmart_create_subscription':
+            return await api.notifications.createSubscription(args.subscriptionData);
+        case 'walmart_get_subscriptions':
+            return await api.notifications.getSubscriptions(args);
+        case 'walmart_get_subscription':
+            return await api.notifications.getSubscription(args.subscriptionId);
+        case 'walmart_update_subscription':
+            return await api.notifications.updateSubscription(args.subscriptionId, args.subscriptionData);
+        case 'walmart_delete_subscription':
+            return await api.notifications.deleteSubscription(args.subscriptionId);
+        case 'walmart_test_subscription':
+            return await api.notifications.testSubscription(args.subscriptionId);
+        // ===== Advertising (Walmart Connect) =====
+        case 'walmart_ad_get_campaigns':
+            return await api.advertising.getCampaigns(args);
+        case 'walmart_ad_create_campaign':
+            return await api.advertising.createCampaign(args.campaignData);
+        case 'walmart_ad_update_campaign':
+            return await api.advertising.updateCampaign(args.campaignData);
+        case 'walmart_ad_delete_campaign':
+            return await api.advertising.deleteCampaign(args.deleteData);
+        case 'walmart_ad_get_ad_groups':
+            return await api.advertising.getAdGroups(args);
+        case 'walmart_ad_create_ad_groups':
+            return await api.advertising.createAdGroups(args.adGroupData);
+        case 'walmart_ad_update_ad_groups':
+            return await api.advertising.updateAdGroups(args.adGroupData);
+        case 'walmart_ad_get_ad_items':
+            return await api.advertising.getAdItems(args);
+        case 'walmart_ad_add_ad_items':
+            return await api.advertising.addAdItems(args.itemData);
+        case 'walmart_ad_update_ad_items':
+            return await api.advertising.updateAdItems(args.itemData);
+        case 'walmart_ad_get_keywords':
+            return await api.advertising.getKeywords(args);
+        case 'walmart_ad_add_keywords':
+            return await api.advertising.addKeywords(args.keywordData);
+        case 'walmart_ad_update_keywords':
+            return await api.advertising.updateKeywords(args.keywordData);
+        case 'walmart_ad_get_keyword_analytics':
+            return await api.advertising.getKeywordAnalytics(args.analyticsData);
+        case 'walmart_ad_create_placement_bids':
+            return await api.advertising.createPlacementBids(args.bidData);
+        case 'walmart_ad_get_placement_bids':
+            return await api.advertising.getPlacementBids(args);
+        case 'walmart_ad_create_platform_bids':
+            return await api.advertising.createPlatformBids(args.bidData);
+        case 'walmart_ad_create_report_snapshot':
+            return await api.advertising.createReportSnapshot(args.reportData);
+        case 'walmart_ad_get_report_snapshots':
+            return await api.advertising.getReportSnapshots(args);
+        case 'walmart_ad_get_realtime_stats':
+            return await api.advertising.getRealtimeStats(args.statsData);
+        case 'walmart_ad_get_latest_report_date':
+            return await api.advertising.getLatestReportDate();
+        case 'walmart_ad_get_item_recommendations':
+            return await api.advertising.getItemRecommendations(args.recommendationData);
+        case 'walmart_ad_get_keyword_recommendations':
+            return await api.advertising.getKeywordRecommendations(args.recommendationData);
+        case 'walmart_ad_get_search_trends':
+            return await api.advertising.getSearchTrends(args.trendData);
+        case 'walmart_ad_get_sba_profile':
+            return await api.advertising.getSbaProfile();
+        // ===== Settings & Configuration =====
+        case 'walmart_get_shipping_settings':
+            return await api.settings.getShippingSettings();
+        case 'walmart_update_shipping_settings':
+            return await api.settings.updateShippingSettings(args.settingsData);
+        case 'walmart_get_fulfillment_centers':
+            return await api.settings.getFulfillmentCenters();
+        case 'walmart_get_partner_info':
+            return await api.settings.getPartnerInfo();
+        // ===== Discovery / escape hatch =====
+        case 'walmart_call_endpoint': {
+            const method = args.method.toUpperCase();
+            const path = args.path;
+            const params = args.params;
+            const body = args.body;
+            const client = api.getMarketplaceClient();
+            switch (method) {
+                case 'GET': return await client.get(path, params);
+                case 'DELETE': return await client.delete(path, params);
+                case 'POST': return await client.post(path, body);
+                case 'PUT': return await client.put(path, body);
+                case 'PATCH': return await client.post(path, body);
+                default:
+                    throw new Error(`Unsupported HTTP method: ${method}`);
+            }
+        }
+        case 'walmart_search_endpoints': {
+            const q = args.query;
+            const limit = args.limit ?? 10;
+            return { query: q, matches: searchEndpoints(q, limit) };
+        }
+        default:
+            throw new Error(`Unknown tool: ${toolName}`);
+    }
+}

package/build/utils/api-error.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Error raised for a non-2xx Walmart API response.
+ *
+ * Carries the HTTP status and the raw response body so callers (and the LLM)
+ * get the full Walmart error detail instead of a lossy `"HTTP 404: Not Found"`
+ * string. Additional context fields (endpoint / tool / hint) are populated by
+ * the request interceptor and the tool dispatcher so the LLM sees:
+ *   - which Walmart endpoint failed
+ *   - which MCP tool triggered it
+ *   - a workaround hint for known-broken Walmart endpoints (Known Issues table)
+ */
+export declare class WalmartApiError extends Error {
+    readonly status: number;
+    readonly details?: unknown | undefined;
+    /** Method + path of the Walmart call, e.g. "GET /v3/returns/count". */
+    readonly endpoint?: string | undefined;
+    /** MCP tool that triggered the call. Filled in by the dispatcher. */
+    tool?: string | undefined;
+    /** Optional workaround hint from src/utils/known-issues.ts. */
+    readonly hint?: string | undefined;
+    constructor(message: string, status: number, details?: unknown | undefined, 
+    /** Method + path of the Walmart call, e.g. "GET /v3/returns/count". */
+    endpoint?: string | undefined, 
+    /** MCP tool that triggered the call. Filled in by the dispatcher. */
+    tool?: string | undefined, 
+    /** Optional workaround hint from src/utils/known-issues.ts. */
+    hint?: string | undefined);
+    /**
+     * Serialize to the JSON shape returned to the MCP client. Optional fields
+     * are omitted when unset to keep error payloads compact.
+     */
+    toResponse(): Record<string, unknown>;
+}
+/**
+ * Build a human/LLM-readable message from a Walmart error response, preserving
+ * as much detail as the body provides:
+ *  - structured `error[]`/`errors[]` → `CODE: description (field: x)`, joined
+ *  - otherwise the raw body (JSON or text), so nothing is silently dropped
+ *  - finally falls back to status + statusText
+ */
+export declare function formatWalmartError(status: number, statusText: string, data: unknown): string;

package/build/utils/api-error.js

@@ -0,0 +1,97 @@
+/**
+ * Error raised for a non-2xx Walmart API response.
+ *
+ * Carries the HTTP status and the raw response body so callers (and the LLM)
+ * get the full Walmart error detail instead of a lossy `"HTTP 404: Not Found"`
+ * string. Additional context fields (endpoint / tool / hint) are populated by
+ * the request interceptor and the tool dispatcher so the LLM sees:
+ *   - which Walmart endpoint failed
+ *   - which MCP tool triggered it
+ *   - a workaround hint for known-broken Walmart endpoints (Known Issues table)
+ */
+export class WalmartApiError extends Error {
+    status;
+    details;
+    endpoint;
+    tool;
+    hint;
+    constructor(message, status, details, 
+    /** Method + path of the Walmart call, e.g. "GET /v3/returns/count". */
+    endpoint, 
+    /** MCP tool that triggered the call. Filled in by the dispatcher. */
+    tool, 
+    /** Optional workaround hint from src/utils/known-issues.ts. */
+    hint) {
+        super(message);
+        this.status = status;
+        this.details = details;
+        this.endpoint = endpoint;
+        this.tool = tool;
+        this.hint = hint;
+        this.name = 'WalmartApiError';
+    }
+    /**
+     * Serialize to the JSON shape returned to the MCP client. Optional fields
+     * are omitted when unset to keep error payloads compact.
+     */
+    toResponse() {
+        const payload = {
+            error: this.message,
+            status: this.status,
+        };
+        if (this.details !== undefined)
+            payload.details = this.details;
+        if (this.endpoint)
+            payload.endpoint = this.endpoint;
+        if (this.tool)
+            payload.tool = this.tool;
+        if (this.hint) {
+            payload.hint = this.hint;
+            payload.isKnownIssue = true;
+        }
+        return payload;
+    }
+}
+/** Walmart uses both `{ errors: [...] }` and `{ error: [...] }` across services. */
+function extractErrors(data) {
+    if (!data || typeof data !== 'object')
+        return [];
+    const obj = data;
+    const raw = obj.errors ?? obj.error;
+    if (Array.isArray(raw))
+        return raw;
+    if (raw && typeof raw === 'object')
+        return [raw];
+    return [];
+}
+function truncate(s, max) {
+    return s.length > max ? `${s.slice(0, max)}…(truncated)` : s;
+}
+/**
+ * Build a human/LLM-readable message from a Walmart error response, preserving
+ * as much detail as the body provides:
+ *  - structured `error[]`/`errors[]` → `CODE: description (field: x)`, joined
+ *  - otherwise the raw body (JSON or text), so nothing is silently dropped
+ *  - finally falls back to status + statusText
+ */
+export function formatWalmartError(status, statusText, data) {
+    const entries = extractErrors(data);
+    if (entries.length) {
+        const parts = entries.map((e) => {
+            const code = e.code ? `${e.code}: ` : '';
+            const desc = e.description || e.message || e.info || '';
+            const field = e.field ? ` (field: ${e.field})` : '';
+            return `${code}${desc}${field}`.trim();
+        });
+        return `HTTP ${status}: ${parts.join('; ')}`;
+    }
+    if (data && typeof data === 'object') {
+        const json = JSON.stringify(data);
+        if (json && json !== '{}')
+            return `HTTP ${status}: ${truncate(json, 500)}`;
+    }
+    else if (typeof data === 'string' && data.trim()) {
+        return `HTTP ${status}: ${truncate(data.trim(), 500)}`;
+    }
+    return `HTTP ${status}: ${statusText}`;
+}

package/build/utils/endpoint-catalog.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Tiny searchable catalog of Walmart Marketplace endpoint patterns and the
+ * dedicated wrapped tools that already cover them. Used by
+ * walmart_search_endpoints to suggest "use this existing tool first".
+ *
+ * Keep this short — it is a discoverability aid, not a full API reference.
+ */
+export interface EndpointEntry {
+    /** Tags for keyword matching. */
+    tags: string[];
+    /** "GET /v3/feeds" — human-friendly. */
+    signature: string;
+    /** Wrapped tool that covers this endpoint, if any. */
+    wrappedTool?: string;
+    /** One-line description. */
+    description: string;
+}
+export declare const ENDPOINT_CATALOG: ReadonlyArray<EndpointEntry>;
+/** Case-insensitive substring + tag-match search. */
+export declare function searchEndpoints(query: string, limit?: number): ReadonlyArray<EndpointEntry & {
+    matchScore: number;
+}>;

package/build/utils/endpoint-catalog.js

@@ -0,0 +1,89 @@
+/**
+ * Tiny searchable catalog of Walmart Marketplace endpoint patterns and the
+ * dedicated wrapped tools that already cover them. Used by
+ * walmart_search_endpoints to suggest "use this existing tool first".
+ *
+ * Keep this short — it is a discoverability aid, not a full API reference.
+ */
+export const ENDPOINT_CATALOG = [
+    // ---------- Items ----------
+    { tags: ['item', 'list', 'catalog'], signature: 'GET /v3/items', wrappedTool: 'walmart_get_all_items', description: 'List items in seller catalog.' },
+    { tags: ['item', 'single', 'sku'], signature: 'GET /v3/items/{sku}', wrappedTool: 'walmart_get_item', description: 'Get single item by SKU.' },
+    { tags: ['item', 'retire', 'delist'], signature: 'DELETE /v3/items/{sku}', wrappedTool: 'walmart_retire_item', description: 'Retire (unpublish) an item.' },
+    { tags: ['taxonomy', 'category'], signature: 'GET /v3/items/taxonomy', wrappedTool: 'walmart_get_taxonomy', description: 'Get Walmart category taxonomy.' },
+    { tags: ['spec', 'attribute'], signature: 'GET /v3/items/spec', wrappedTool: 'walmart_get_item_spec', description: 'Get required attributes for a product type.' },
+    { tags: ['hazmat', 'onhold'], signature: 'POST /v3/items/onhold/search', wrappedTool: 'walmart_get_hazmat_items', description: 'Search items on hold for hazmat review.' },
+    // ---------- Inventory ----------
+    { tags: ['inventory', 'stock', 'sku'], signature: 'GET /v3/inventory', wrappedTool: 'walmart_get_inventory', description: 'Get inventory for a SKU.' },
+    { tags: ['inventory', 'update', 'stock'], signature: 'PUT /v3/inventory', wrappedTool: 'walmart_update_inventory', description: 'Update inventory for a SKU.' },
+    { tags: ['inventory', 'multi-node', 'ship-node'], signature: 'GET /v3/inventories', wrappedTool: 'walmart_get_inventory_all_nodes', description: 'Get inventory across all ship nodes.' },
+    { tags: ['lag', 'lag-time'], signature: 'GET /v3/lagtime', wrappedTool: 'walmart_get_lag_time', description: 'Get fulfillment lag time for a SKU.' },
+    // ---------- Pricing ----------
+    { tags: ['price', 'update', 'base'], signature: 'PUT /v3/price', wrappedTool: 'walmart_update_price', description: 'Update base price for a SKU.' },
+    { tags: ['promo', 'promotion', 'sale', 'discount'], signature: 'POST /v3/feeds?feedType=PROMO_PRICE', wrappedTool: 'walmart_submit_promo_price_feed', description: 'Submit a promotional price feed.' },
+    { tags: ['repricer', 'buy-box', 'compete'], signature: 'GET /v3/repricer/strategies', wrappedTool: 'walmart_get_repricer_strategies', description: 'List repricer strategies (Pro Seller).' },
+    // ---------- Feeds ----------
+    { tags: ['feed', 'status'], signature: 'GET /v3/feeds/{feedId}', wrappedTool: 'walmart_get_feed_status', description: 'Get feed processing status.' },
+    { tags: ['feed', 'list', 'history'], signature: 'GET /v3/feeds', wrappedTool: 'walmart_get_all_feed_statuses', description: 'List recent feeds.' },
+    { tags: ['feed', 'submit'], signature: 'POST /v3/feeds', wrappedTool: 'walmart_submit_inventory_feed', description: 'Submit a bulk feed. Use feed-type-specific tools (walmart_submit_inventory_feed, walmart_submit_item_feed, walmart_submit_promo_price_feed) for strict validation.' },
+    // ---------- Orders ----------
+    { tags: ['order', 'list'], signature: 'GET /v3/orders', wrappedTool: 'walmart_get_all_orders', description: 'List orders with filters.' },
+    { tags: ['order', 'released', 'ready'], signature: 'GET /v3/orders/released', wrappedTool: 'walmart_get_released_orders', description: 'List orders ready for fulfillment.' },
+    { tags: ['order', 'single', 'purchase-order'], signature: 'GET /v3/orders/{poId}', wrappedTool: 'walmart_get_order', description: 'Get single order by purchase order ID.' },
+    { tags: ['acknowledge', 'ack', 'order'], signature: 'POST /v3/orders/{poId}/acknowledge', wrappedTool: 'walmart_acknowledge_order', description: 'Acknowledge a new order.' },
+    { tags: ['ship', 'shipment', 'tracking'], signature: 'POST /v3/orders/{poId}/shipping', wrappedTool: 'walmart_ship_order', description: 'Mark order lines as shipped.' },
+    { tags: ['cancel', 'order'], signature: 'POST /v3/orders/{poId}/cancel', wrappedTool: 'walmart_cancel_order', description: 'Cancel order lines.' },
+    { tags: ['refund', 'order'], signature: 'POST /v3/orders/{poId}/refund', wrappedTool: 'walmart_refund_order', description: 'Refund order lines (negative amount).' },
+    // ---------- Returns ----------
+    { tags: ['return', 'list'], signature: 'GET /v3/returns', wrappedTool: 'walmart_get_all_returns', description: 'List returns.' },
+    { tags: ['return', 'single'], signature: 'GET /v3/returns/{returnOrderId}', wrappedTool: 'walmart_get_return', description: 'Get single return.' },
+    { tags: ['return', 'approve'], signature: 'POST /v3/returns/approve', wrappedTool: 'walmart_approve_return', description: 'Approve a return.' },
+    { tags: ['return', 'reject'], signature: 'POST /v3/returns/reject', wrappedTool: 'walmart_reject_return', description: 'Reject a return.' },
+    { tags: ['return', 'refund'], signature: 'POST /v3/returns/{rid}/items/{iid}/refund', wrappedTool: 'walmart_issue_return_refund', description: 'Issue refund for a return.' },
+    { tags: ['return', 'label', 'shipping'], signature: 'POST /v3/returns/{rid}/items/{iid}/shippinglabel', wrappedTool: 'walmart_generate_return_label', description: 'Generate return shipping label.' },
+    // ---------- Reports ----------
+    { tags: ['report', 'request', 'generate'], signature: 'POST /v3/reports/reportRequests', wrappedTool: 'walmart_create_report', description: 'Request generation of a report.' },
+    { tags: ['report', 'status'], signature: 'GET /v3/reports/reportRequests/{id}', wrappedTool: 'walmart_get_report_status', description: 'Check report generation status.' },
+    { tags: ['report', 'download'], signature: 'GET /v3/reports/reportRequests/{id}/download', wrappedTool: 'walmart_download_report', description: 'Download a READY report.' },
+    { tags: ['report', 'schedule', 'recurring'], signature: 'POST /v3/reports/reportSchedules', wrappedTool: 'walmart_create_report_schedule', description: 'Create a recurring report schedule.' },
+    // ---------- Notifications / Webhooks ----------
+    { tags: ['webhook', 'subscription', 'notification'], signature: 'GET /v3/notifications/subscriptions', wrappedTool: 'walmart_get_subscriptions', description: 'List webhook subscriptions.' },
+    { tags: ['webhook', 'create'], signature: 'POST /v3/notifications/subscriptions', wrappedTool: 'walmart_create_subscription', description: 'Create a webhook subscription.' },
+    // ---------- Insights ----------
+    { tags: ['quality', 'listing-quality', 'score'], signature: 'GET /v3/insights/items/listingQuality', wrappedTool: 'walmart_get_listing_quality', description: 'Get store listing quality score.' },
+    // ---------- Settings / Partner ----------
+    { tags: ['partner', 'seller-info', 'account'], signature: 'GET /v3/partner/info', wrappedTool: 'walmart_get_partner_info', description: 'Get partner account info.' },
+    { tags: ['fulfillment-center', 'ship-node'], signature: 'GET /v3/shipping/labels/fulfillmentcenters', wrappedTool: 'walmart_get_fulfillment_centers', description: 'List fulfillment centers.' },
+    // ---------- Auth / Diagnostics ----------
+    { tags: ['token', 'auth', 'oauth'], signature: 'POST /v3/token', wrappedTool: 'walmart_get_token', description: 'Get OAuth Bearer token.' },
+    { tags: ['rate', 'budget', 'limit'], signature: '(internal)', wrappedTool: 'walmart_get_rate_budget', description: 'Snapshot local + server rate-limit state.' },
+];
+/** Case-insensitive substring + tag-match search. */
+export function searchEndpoints(query, limit = 10) {
+    const q = query.toLowerCase().trim();
+    if (!q)
+        return [];
+    const tokens = q.split(/\s+/).filter(Boolean);
+    const scored = [];
+    for (const entry of ENDPOINT_CATALOG) {
+        let score = 0;
+        const tagBag = entry.tags.join(' ').toLowerCase();
+        const sigBag = entry.signature.toLowerCase();
+        const descBag = entry.description.toLowerCase();
+        const toolBag = (entry.wrappedTool ?? '').toLowerCase();
+        for (const tok of tokens) {
+            if (tagBag.includes(tok))
+                score += 3;
+            if (toolBag.includes(tok))
+                score += 2;
+            if (sigBag.includes(tok))
+                score += 2;
+            if (descBag.includes(tok))
+                score += 1;
+        }
+        if (score > 0)
+            scored.push({ ...entry, matchScore: score });
+    }
+    scored.sort((a, b) => b.matchScore - a.matchScore);
+    return scored.slice(0, limit);
+}

package/build/utils/env-file.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Insert or update `KEY=VALUE` pairs in a .env file, preserving the rest of
+ * the file. An existing (optionally commented-out) line for a key is replaced
+ * in place; otherwise the pair is appended.
+ *
+ * The replacement uses a *function* form of `String.prototype.replace` so that
+ * values containing `$` sequences (e.g. `$1`, `$&`, `$$`) are written literally
+ * instead of being interpreted as regex replacement patterns. Walmart access
+ * tokens and client secrets are opaque and can contain `$`, which would
+ * otherwise corrupt the persisted value and break authentication on restart.
+ */
+export declare function upsertEnvVars(updates: Record<string, string>, envPath?: string): void;