@lehaotech/walmart-mcp 0.5.4

package/.env.example

@@ -0,0 +1,25 @@
+# Required
+WALMART_CLIENT_ID=your-client-id
+WALMART_CLIENT_SECRET=your-client-secret
+
+# Optional (defaults shown)
+WALMART_ENVIRONMENT=sandbox
+WALMART_MARKET=us
+WALMART_SVC_NAME=Walmart Marketplace
+
+# Optional
+WALMART_CONSUMER_CHANNEL_TYPE=
+WALMART_PARTNER_ID=
+
+# Token cache (auto-managed)
+WALMART_ACCESS_TOKEN=
+WALMART_ACCESS_TOKEN_EXPIRY=
+
+# Logging
+WALMART_LOG_LEVEL=info
+WALMART_ENABLE_FILE_LOGGING=false
+
+# Advertising (Walmart Connect) - separate credentials
+WALMART_AD_CONSUMER_ID=
+WALMART_AD_PRIVATE_KEY=
+WALMART_AD_KEY_VERSION=1

package/CHANGELOG.md

@@ -0,0 +1,247 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres
+to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.5.4] - 2026-06-29
+
+### Fixed
+- **Corrupt `package-lock.json`**: the lock file ended mid-line inside a
+  `source-map-js` `resolved` URL — invalid JSON. `npm ci` in CI rejected it
+  with `EUSAGE: The npm ci command can only install with an existing
+  package-lock.json ... with lockfileVersion >= 1` (npm's fallback message
+  when lock JSON parse fails). Regenerated cleanly via `npm install` on
+  Windows. Local `npm run test:run` was unaffected because it doesn't require
+  the lock file (uses already-populated `node_modules`). 0.5.3 git tag exists
+  but its CI Test step failed for this reason, so 0.5.3 also never published.
+
+## [0.5.3] - 2026-06-29
+
+### Fixed
+- **Release workflow `npm publish --provenance` failed** in 0.5.2 with
+  `EUSAGE: Provenance generation in GitHub Actions requires "write" access to
+  the "id-token" permission`. The workflow only requested `contents: write`,
+  but `--provenance` needs OIDC token issuance. Added `id-token: write` to
+  `.github/workflows/release.yml` `permissions:`. 0.5.2 never reached npm —
+  0.5.4 is the first published version under the `@lehaotech` scope.
+- **MCP server version drift**: `src/index.ts` reported `0.3.2` to MCP clients
+  regardless of the published version (lagged through five releases). The
+  server now reads `version` from `package.json` at startup so what the client
+  sees always matches the installed npm version. The `walmart-mcp version`
+  subcommand reuses the same resolver.
+- **CI coverage gate** failed (`Process completed with exit code 1`) because
+  the 70/70/70/70 threshold was set before the dispatch and oauth layers were
+  fully covered. Coverage actually measures 87.27/86.77/59.2/87.27 — functions
+  drag from `src/auth/oauth.ts` being 0% (no oauth unit tests yet, see issue
+  backlog). Recalibrated to 50/40/50/50 — still meaningful gating against the
+  current 249-test baseline. `src/utils/logger.ts` (winston config, no
+  branches) added to coverage exclude.
+
+### Notes
+- The git tag `v0.5.2` exists in history but corresponds to a release that
+  never published. Anyone fetching it gets the same source tree minus this
+  changelog entry and the three fixes above.
+
+## [0.5.2] - 2026-06-29
+
+### Changed
+- **npm package name renamed** from `@yufakang0826-hue/walmart-mcp` to
+  `@lehaotech/walmart-mcp` to match the maintainer's npm scope. The GitHub
+  repo (`yufakang0826-hue/walmart-mcp`) is unchanged.
+
+### Notes
+- Reinstall users: `npm install -g @lehaotech/walmart-mcp` (old scope is not published).
+
+## [0.5.1] - 2026-06-29
+
+### Fixed
+- **`tests/tools/tool-definitions.test.ts`** hard-coded tool count was still
+  `127`; updated to `130` to account for the three new discovery/budget tools
+  added in 0.5.0 (`walmart_call_endpoint`, `walmart_search_endpoints`,
+  `walmart_get_rate_budget`). Without this fix the v0.5.0 push fails CI.
+- **`tests/api/client-interceptor.test.ts`** retries-5xx-up-to-3-times test
+  triggered an "unhandled promise rejection" warning under Vitest because the
+  rejected promise was observed only after a series of `vi.advanceTimersByTimeAsync`
+  calls. Added an inline `.catch(() => {})` to tag the promise as handled.
+  No functional change.
+
+### Notes
+- Test suite: 249 passing, 0 failed, 0 unhandled rejections.
+
+## [0.5.0] - 2026-06-29
+
+### Added
+- **Discovery escape-hatch tools** for endpoints not covered by a dedicated
+  wrapped tool:
+  - `walmart_call_endpoint({ method, path, params?, body? })` calls any
+    Walmart Marketplace endpoint with the same auth / retry / rate-limit
+    pipeline as wrapped tools.
+  - `walmart_search_endpoints({ query, limit? })` searches a 40+ entry
+    catalog (`src/utils/endpoint-catalog.ts`) and suggests the wrapped tool
+    that already covers it.
+- **`walmart_get_rate_budget`**: returns the local sliding-window state plus
+  the latest Walmart-server-reported token bucket
+  (`x-current-token-count` + `x-next-replenish-time`). RateLimiter now
+  exposes `getStatus()`. Includes a note that Walmart does NOT have an
+  OAuth user-token flow; rate limits depend on seller-account tier.
+- **Subcommand bin**: `walmart-mcp [setup|diagnose|version|help]`. A single
+  installed binary handles server start, interactive setup, self-check, and
+  version printing. Argv is forwarded so `walmart-mcp diagnose --export`
+  works as expected.
+- **Multi-MCP-client setup**: setup wizard detects and writes
+  Claude Desktop, Claude Code CLI, Cursor, Cline, Continue.dev,
+  Windsurf, and Zed. Multi-select via comma-separated indices. Zed's
+  nested `mcp.servers` shape is handled.
+- **Three GitHub Actions workflows**:
+  - `release.yml` triggers on `v*.*.*` tag, runs typecheck + tests + build,
+    enforces tag/package.json version agreement, publishes to npm with
+    `--provenance --access public`, and creates a GitHub Release.
+  - `sandbox.yml` runs `npm run test:sandbox` on a weekly cron and on
+    `workflow_dispatch` with environment input (sandbox/production). Uses
+    repository secrets `WALMART_CLIENT_ID/SECRET`, optional Ads creds.
+- **Known Issues table doubled** from 6 to 13 entries: WFS program-gating
+  (404 for sellers without WFS enrollment), Ship-with-Walmart carriers,
+  Walmart Repricer 403 enrollment, Webhooks allowlist, expired report
+  download URLs, and Walmart Connect ads catch-all.
+- **`package.json` files field** now includes `CHANGELOG.md` so npm users
+  can read release notes locally.
+- **Tests**: `+45` new tests across `endpoint-catalog`, `discovery-schema`,
+  `client-configs`, `rate-limiter.getStatus`, `index-wrapper` (zod
+  re-parse path), and the expanded known-issues table. Suite is expected
+  to be 249 passing on completion (up from 114 baseline of v0.3.2).
+
+### Changed
+- **Dispatcher zod re-parse**: the MCP wrapper in `src/index.ts` now runs
+  `z.object(toolDef.inputSchema).parse(rawArgs)` BEFORE calling the
+  dispatcher. This guarantees `.refine()` business rules execute and
+  `.default()` values are filled in, regardless of how the MCP client
+  handled the JSON Schema upstream. ZodErrors are returned as a structured
+  payload with `issues[]` (path + message + code) so the LLM can correct
+  itself without seeing a stack trace.
+- **`WalmartSellerApi`** exposes `getMarketplaceClient()` and
+  `getRateLimiterStatus()` to support the new Discovery + rate-budget
+  tools. The marketplace client (`WalmartApiClient`) exposes
+  `getRateLimiter()`.
+- **Setup wizard** factored its config-write logic into
+  `src/scripts/client-configs.ts` so the single `writeWalmartEntry()`
+  helper handles all 7 supported clients (and the Zed-nested case).
+
+### Notes
+- Still 0 new runtime dependencies. The new bin subcommand uses dynamic
+  `import('./scripts/...')` so the setup / diagnose scripts only load when
+  invoked, keeping cold start of the MCP server fast.
+- npm package size: ~58 KB tarball, ~340 KB unpacked, 82 files.
+
+## [0.4.0] - 2026-06-29
+
+### Added
+- **`npm run diagnose`** self-check: validates Node version, `.env`, required
+  + optional env vars, performs a live Walmart token exchange, and inspects
+  MCP-client config (Claude Desktop / Claude Code CLI / Cursor) for a
+  registered `walmart` server. Exits non-zero on errors; `--export` dumps
+  JSON for bug attachments. Zero new runtime deps.
+- **`npm run setup`** interactive wizard: environment + market choice,
+  masked credential input, live token validation, optional Walmart Connect
+  advertising config, Claude Desktop config write with automatic backup.
+  Never echoes the secret. Claude Desktop only for now.
+- **README "Known Issues" section** documenting 8 Walmart-side endpoint
+  regressions, program-gated tool groups (Repricer / Walmart Connect / WFS),
+  and the `walmart_get_wfs_returns` behavior note.
+- **`src/utils/known-issues.ts`** — single source of truth for hint lookup
+  used by the error layer. 6 documented broken/changed endpoints with
+  workaround hints.
+- **`src/tools/definitions/shared-schemas.ts`** — 9 reusable zod atoms
+  (Sku, Gtin, ShipNode, Money, Iso8601Utc, Quantity, ProcessMode, etc.)
+  used across module definitions.
+- **GitHub Actions CI** (`.github/workflows/ci.yml`): typecheck / vitest /
+  build on Node 22 + 24 (Ubuntu) and Node 22 (Windows). Smoke-runs diagnose
+  and uploads the JSON report as an artifact.
+- **`typecheck` script** (`tsc --noEmit`).
+- **69 new unit + integration tests** across `known-issues`,
+  `shared-schemas`, `strict-schemas` (business-rule refinements), extended
+  `api-error`, and `client-interceptor` (401 retry / 429 / 5xx exponential
+  backoff / endpoint + hint injection). Suite grew 114 -> ~183 passing.
+
+### Changed
+- **Schema hardening** across 54 write tools: replaced
+  `z.record(z.string(), z.unknown())` payloads with strict zod schemas
+  mirroring Walmart spec. Pricing 6, orders 5, fulfillment 7, returns 4,
+  items 5, inventory 4, reports 3, advertising 12, notifications 2,
+  settings 1. Examples of enforced business rules:
+  - PROMO_PRICE: `currentPrice < comparisonPrice`, same currency on both,
+    `effectiveDate >= now + 4h`, duration ≤ 180 days, ≤ 10 promos / SKU,
+    ≤ 10000 SKUs / feed.
+  - INVENTORY: integer non-negative quantities, lag time 0-28 days.
+  - MP_ITEM envelope: required `MPItemFeedHeader` + non-empty `MPItem`;
+    each `Item` has a strict SKU; per-attribute fields passthrough.
+  - REFUND: chargeAmount.amount must be negative.
+  - SUBSCRIPTION: destinationUrl must be HTTPS.
+
+  Only 2 loose `z.record()` payloads remain by design (the generic-feed
+  escape hatch and the WFS `shipmentInfo` sub-field where Walmart docs
+  are sparse).
+
+- **`WalmartApiError`** carries `endpoint`, `tool`, and `hint` fields in
+  addition to status + details. A new `toResponse()` method serializes
+  only set fields and marks `isKnownIssue: true` whenever a hint is
+  present.
+- **API client interceptor** populates `endpoint` (e.g.
+  `GET /v3/returns/count`) and looks up the workaround hint from
+  `known-issues.ts` on every 4xx/5xx.
+- **MCP tool dispatcher** injects the tool name into `WalmartApiError.tool`
+  and emits the enriched payload via `error.toResponse()`. The LLM now
+  receives `{ error, status, endpoint, tool, hint, isKnownIssue }`
+  instead of a bare error string.
+- **`.gitattributes`** added to lock LF line endings on `.ts/.json/.md`
+  files, eliminating spurious CRLF↔LF diffs from Windows editors.
+
+### Notes
+- No new runtime dependencies; all new scripts use Node built-ins
+  (`readline/promises`, `fetch`).
+- `npm test` on Linux requires re-installing native esbuild bins if
+  `node_modules` was copied across OS boundaries — `npm ci` resolves it.
+
+## [0.3.2] - 2026-06-01
+
+### Fixed
+- API errors no longer collapse Walmart's response body into a bare
+  `"HTTP 404: Not Found"`. A new `WalmartApiError` carries the HTTP status and
+  raw body; `formatWalmartError` surfaces every `error[]`/`errors[]` entry
+  (`CODE: description (field: x)`) or the raw body when unstructured, and tool
+  results now include `status` and `details`. Applied to both the marketplace
+  and advertising clients.
+- `walmart_get_hazmat_items` pointed at the non-existent `/v3/items/hazmat`
+  (405). Repointed to the documented on-hold search endpoint
+  `POST /v3/items/onhold/search`; the request body is now optional.
+
+### Changed
+- `walmart_update_price` takes semantic params again (`sku`, `amount`,
+  optional `currency`) instead of an opaque `pricing` object. The server builds
+  the Walmart `/v3/price` payload, restoring field-level validation and the
+  ergonomics of the older listing MCP. Promotional/strikethrough pricing
+  remains in `walmart_submit_promo_price_feed`.
+
+### Added
+- Tests for `formatWalmartError`/`WalmartApiError`, the rebuilt price payload,
+  and the corrected hazmat endpoint. Suite grew from 121 to 132 passing tests.
+
+### Notes
+- The test report's `get_wfs_returns` "duplicate data" finding is not a code
+  defect: `GET /v3/returns?isWFSEnabled=Y` is the documented call and is sent
+  correctly; Walmart returns the unfiltered set for accounts not enrolled in
+  WFS. Left as-is.
+- `get_item_quality_details` (405) and `get_shipping_settings` (404) are not
+  changed: the correct endpoints could not be confirmed against authoritative
+  docs, and guessing endpoints is exactly the failure mode to avoid. They need
+  live sandbox verification.
+
+## [0.3.1] - 2026-06-01
+
+### Fixed
+- Persisting tokens/credentials to `.env` corrupted any value containing `$`
+  sequences (`$1`, `$&`, `$$`). `String.prototype.replace` interpreted them as
+  replacement patterns, so a Walmart access token or client secret with a `$`
+  was written mangled — breaking auth on the next restart. The shared
+  `upsertEnvVars` helper now uses the function form of `replace` to write values
+  literally. Affected `oa

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fakang Yu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,344 @@
+# walmart-mcp
+
+[![CI](https://github.com/yufakang0826-hue/walmart-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/yufakang0826-hue/walmart-mcp/actions/workflows/ci.yml)
+[![Release](https://github.com/yufakang0826-hue/walmart-mcp/actions/workflows/release.yml/badge.svg)](https://github.com/yufakang0826-hue/walmart-mcp/actions/workflows/release.yml)
+[![codecov](https://codecov.io/gh/yufakang0826-hue/walmart-mcp/branch/master/graph/badge.svg)](https://codecov.io/gh/yufakang0826-hue/walmart-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](https://nodejs.org/)
+[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-blue.svg)](https://modelcontextprotocol.io/)
+![Tools](https://img.shields.io/badge/tools-130-orange.svg)
+![Tests](https://img.shields.io/badge/tests-249%20passing-success.svg)
+
+```
+                  _                       _                            
+                 | |                     | |                           
+ __      ____ _  | |_ __ ___   __ _ _ __ | |_ ______ _ __ ___   ___ _ __
+ \ \ /\ / / _` | | | '_ ` _ \ / _` | '__|| __||_____| '_ ` _ \ / __| '_ \
+  \ V  V / (_| | | | | | | | | (_| | |   | |_       | | | | | | (__| |_) |
+   \_/\_/ \__,_| |_|_| |_| |_|\__,_|_|    \__|      |_| |_| |_|\___| .__/
+                                                                   | |  
+   AI-native Walmart Marketplace toolkit — 130 strict-zod tools     |_|  
+   Discovery escape hatch · Token bucket monitor · Hint-driven errors
+```
+
+| | |
+|---|---|
+| **Install** | `npm install -g @lehaotech/walmart-mcp` |
+| **Onboard** | `walmart-mcp setup` (7 MCP clients auto-detected) |
+| **Self-check** | `walmart-mcp diagnose --export` |
+| **Docs** | [Quick Start](#5-minute-quick-start) · [Tools](#modules) · [Known Issues](#known-issues) · [Contributing](./CONTRIBUTING.md) · [Architecture](./docs/architecture.md) |
+| **Status** | v0.5.0 (npm) · 249 tests passing · 70% coverage threshold · 3 GitHub Actions workflows |
+| **License** | MIT |
+
+A Model Context Protocol (MCP) server for the Walmart Marketplace Seller API.
+130 tools covering items, inventory, orders, pricing, fulfillment (WFS),
+returns, reports, notifications, and advertising (Walmart Connect) — plus a
+Discovery escape hatch that lets AI agents call any other Walmart endpoint
+through the same auth + retry + rate-limit pipeline.
+
+## 5-minute Quick Start
+
+```bash
+# 1. Install the published package
+npm install -g @lehaotech/walmart-mcp
+
+# 2. Run the interactive setup wizard. It will:
+#    - ask for environment + market (sandbox / production, us / mx / ca / cl)
+#    - take your Walmart Client ID + Secret (masked input)
+#    - LIVE-VALIDATE the credentials by exchanging an OAuth token
+#    - detect which MCP clients you have installed (Claude Desktop, Cursor,
+#      Cline, Continue.dev, Windsurf, Zed, Claude Code CLI) and write the
+#      walmart MCP entry into each one you pick — with automatic backup
+walmart-mcp setup
+
+# 3. Restart your AI client. Try a prompt like:
+#    "Show me my recent Walmart orders"
+```
+
+If something does not work, run the built-in self-check:
+
+```bash
+walmart-mcp diagnose            # 7-step health check
+walmart-mcp diagnose --export   # also dumps walmart-mcp-diagnose.json for bug reports
+```
+
+Other subcommands: `walmart-mcp version`, `walmart-mcp help`.
+
+## Features
+
+- **130 tools** across 13 modules (items / inventory / orders / pricing /
+  fulfillment / returns / reports / notifications / advertising / settings
+  / token / discovery)
+- **Strict zod schemas on every write tool**: 54 write tools enforce Walmart
+  business rules (promo < base, `effectiveDate >= now + 4h`, refunds must be
+  negative, subscription URLs must be HTTPS, etc.) BEFORE the API call so
+  LLMs get structured validation errors and self-correct without burning
+  Walmart API quota.
+- **LLM-friendly error responses**: every 4xx/5xx carries `endpoint`, `tool`,
+  and (for documented broken Walmart endpoints) a `hint` field with the
+  workaround the LLM should try next — backed by a single source of truth
+  `src/utils/known-issues.ts` mirrored into this README.
+- **Token refresh, rate limiting, and retry built in**: 15-minute OAuth Bearer
+  auto-refresh, sliding-window throttle, 401 (refresh + retry once), 429
+  (rate-limit error with `retry-after`), 423 (resource lock retry), and
+  5xx (exponential backoff up to 3 retries).
+- **Rate budget monitor**: `walmart_get_rate_budget` returns the local
+  sliding-window state plus the latest Walmart-server-reported token bucket
+  (`x-current-token-count` + `x-next-replenish-time`).
+- **Discovery escape hatch**: `walmart_call_endpoint` + `walmart_search_endpoints`
+  cover the long tail. Same auth / retry / rate-limit pipeline as wrapped tools.
+- **CI + sandbox + release workflows**: typecheck + tests run on every PR
+  (Node 22 + 24, Ubuntu + Windows); tag pushes auto-publish to npm with
+  provenance; weekly cron hits the real Walmart sandbox.
+
+## Modules
+
+| Module | Tools | Description |
+|--------|-------|-------------|
+| Token Management | 7 | Credentials, token lifecycle, setup guide, rate budget |
+| Items | 12 | CRUD, taxonomy, feeds, WFS conversion |
+| Inventory | 10 | Single/multi-node, lag time, feeds |
+| Orders | 10 | Fulfill, ship, cancel, refund, labels |
+| Pricing | 10 | Price updates, repricer strategies |
+| Feeds | 5 | Submit, poll, status tracking |
+| WFS Fulfillment | 19 | Inbound shipments, MCS, carrier booking |
+| Returns | 8 | Approve, reject, refund, labels |
+| Reports | 12 | On-demand, scheduled, listing quality |
+| Notifications | 6 | Webhook subscriptions |
+| Advertising | 25 | Campaigns, keywords, bids, analytics |
+| Settings | 4 | Shipping, fulfillment centers, partner |
+| **Discovery** | **2** | **`walmart_call_endpoint` + `walmart_search_endpoints`** |
+
+## Installation
+
+### From npm (recommended)
+
+```bash
+npm install -g @lehaotech/walmart-mcp
+```
+
+The unscoped name `walmart-mcp` on npm belongs to a different author. Use the
+scoped package above.
+
+### From source
+
+```bash
+git clone https://github.com/yufakang0826-hue/walmart-mcp.git
+cd walmart-mcp
+npm install
+npm run build
+```
+
+## Configuration
+
+The simplest path is `walmart-mcp setup` — it writes the MCP config for you and
+validates credentials against Walmart before saving.
+
+If you want to configure manually, the entry looks like:
+
+```jsonc
+{
+  "mcpServers": {
+    "walmart": {
+      "type": "stdio",
+      "command": "walmart-mcp",
+      "env": {
+        "WALMART_CLIENT_ID": "your-client-id",
+        "WALMART_CLIENT_SECRET": "your-client-secret",
+        "WALMART_ENVIRONMENT": "sandbox",
+        "WALMART_MARKET": "us"
+      }
+    }
+  }
+}
+```
+
+Setup wizard auto-detects these locations:
+
+| Client | Config path |
+|---|---|
+| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Claude Desktop (Windows) | `%APPDATA%/Claude/claude_desktop_config.json` |
+| Claude Desktop (Linux) | `~/.config/Claude/claude_desktop_config.json` |
+| Claude Code CLI | `~/.claude.json` |
+| Cursor | `~/.cursor/mcp.json` |
+| Cline (VSCode) | `~/.../globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` |
+| Continue.dev | `~/.continue/config.json` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
+| Zed | OS-dependent, with `mcp.servers` nesting |
+
+### Environment Variables
+
+```bash
+# Required — Marketplace API
+WALMART_CLIENT_ID=your-client-id
+WALMART_CLIENT_SECRET=your-client-secret
+
+# Optional (defaults shown)
+WALMART_ENVIRONMENT=sandbox        # sandbox | production
+WALMART_MARKET=us                  # us | mx | ca | cl
+WALMART_SVC_NAME=Walmart Marketplace
+
+# Optional — Advertising (Walmart Connect)
+WALMART_AD_CONSUMER_ID=your-ad-consumer-id
+WALMART_AD_PRIVATE_KEY=your-private-key
+WALMART_AD_KEY_VERSION=1
+
+# Logging
+WALMART_LOG_LEVEL=info             # error | warn | info | http | debug
+WALMART_ENABLE_FILE_LOGGING=false
+```
+
+## Getting Walmart API Credentials
+
+1. Sign up at [Walmart Developer Portal](https://developer.walmart.com/)
+2. Create a new application under **Marketplace**
+3. Copy the **Client ID** and **Client Secret**
+4. For advertising, apply for [Walmart Connect](https://www.walmartconnect.com/) access
+
+## Usage Examples
+
+```
+"Get all my Walmart orders from the last 7 days"
+→ walmart_get_all_orders({ createdStartDate, createdEndDate })
+
+"Update inventory for SKU ABC-123 to 50 units"
+→ walmart_update_inventory({ sku, quantity })
+
+"Submit a 7-day 20% promo on SKU XYZ starting tomorrow"
+→ walmart_submit_promo_price_feed({ feedData: { ... } })
+  (zod refinements enforce promo<base, >=4h lead, <=180 days, etc.)
+
+"What is my current Walmart rate-limit budget?"
+→ walmart_get_rate_budget()
+  { localRemaining: 996, serverTokensRemaining: 18,
+    serverReplenishTime: "2026-06-29T15:30:00Z", ... }
+
+"Find the right Walmart tool for downloading a settlement report"
+→ walmart_search_endpoints({ query: "settlement report" })
+  [{ wrappedTool: "walmart_create_report", signature: "POST /v3/reports/reportRequests", ... }]
+
+"Call GET /v3/items/walmart-item/<wpid>" (no wrapped tool yet)
+→ walmart_call_endpoint({ method: "GET", path: "/v3/items/walmart-item/123" })
+```
+
+## Development
+
+```bash
+npm run build           # tsc + tsc-alias -> build/
+npm run dev             # tsx src/index.ts (no build step)
+npm run typecheck       # tsc --noEmit
+npm run inspect         # MCP Inspector against built bin
+npm test                # vitest watch
+npm run test:run        # vitest single run (CI)
+npm run test:sandbox    # real Walmart sandbox smoke (skips when no creds)
+```
+
+The unit suite covers the tool dispatcher, every API module, the RSA-SHA256
+advertising signature, the sliding-window rate limiter, the zod schemas (atom
++ business-rule refinements), the API client's response interceptor (401 / 429
+/ 423 / 5xx retry + endpoint/hint injection), the known-issues lookup, the
+endpoint catalog search, the multi-client config write, and the dispatcher's
+zod re-parse path.
+
+`test:sandbox` exercises ~15 read-only calls (token, partner info, items,
+orders, returns, feeds, pricing strategies, listing quality, rate budget,
+endpoint search) end-to-end. It requires real credentials and **skips
+gracefully** (exit 0) when they are absent, so it is safe to run in CI.
+
+The `sandbox.yml` workflow runs this weekly on a cron + on `workflow_dispatch`,
+using repo secrets `WALMART_CLIENT_ID` / `WALMART_CLIENT_SECRET` (+ optional
+Ads creds).
+
+## Architecture
+
+```
+src/
+├── index.ts                              # MCP server entry + subcommand dispatch
+├── scripts/
+│   ├── diagnose.ts                       # walmart-mcp diagnose (7-step self-check)
+│   ├── setup.ts                          # walmart-mcp setup (interactive wizard)
+│   └── client-configs.ts                 # 7 MCP client config paths + write helper
+├── config/environment.ts                 # Config & env vars
+├── auth/oauth.ts                         # OAuth 2.0 token management
+├── utils/
+│   ├── logger.ts                         # Winston logger (stderr only)
+│   ├── rate-limiter.ts                   # Sliding-window + getStatus() snapshot
+│   ├── api-error.ts                      # WalmartApiError w/ endpoint+tool+hint
+│   ├── known-issues.ts                   # Lookup table for hint injection
+│   ├── endpoint-catalog.ts               # 40+ entries for walmart_search_endpoints
+│   └── env-file.ts                       # .env upsert helper
+├── api/
+│   ├── client.ts                         # Marketplace HTTP client + interceptors
+│   ├── index.ts                          # API facade (WalmartSellerApi)
+│   ├── advertising/                      # RSA-SHA256 signed Ads client + 25 methods
+│   └── (items|inventory|orders|pricing|feeds|fulfillment|returns|reports|notifications|settings)/
+└── tools/
+    ├── index.ts                          # Tool registry + dispatcher
+    └── definitions/
+        ├── shared-schemas.ts             # 9 atomic zod schemas reused across modules
+        ├── discovery.ts                  # walmart_call_endpoint + walmart_search_endpoints
+        └── <module>.ts                   # 12 per-module wrapped tools
+```
+
+## Known Issues
+
+This MCP wraps Walmart's public Marketplace API. A handful of tools surface
+known limitations from Walmart's side (broken endpoints, programs you have
+not enrolled in) rather than MCP-side bugs. The tools are kept in place for
+forward compatibility and will work once Walmart restores the endpoint or
+you enroll in the program.
+
+When these endpoints fail, the MCP error response includes a `hint` field
+pointing the LLM at the recommended workaround. The complete list is
+maintained in `src/utils/known-issues.ts` (single source of truth).
+
+### Walmart-side endpoint regressions
+
+| Tool | Symptom | Workaround |
+| --- | --- | --- |
+| `walmart_get_unpublished_items` | HTTP 404 from Insights `/v3/insights/items/unpublished/counts` (Aurora backend regression since 2026-05) | `walmart_get_all_items` + filter on `publishedStatus = "UNPUBLISHED"` client-side |
+| `walmart_get_quality_categories` | HTTP 404 from Insights API | None — endpoint removed. Use `walmart_get_item_quality_details` per SKU when fixed. |
+| `walmart_get_item_quality_details` | HTTP 405 Method Not Allowed | None right now — endpoint signature changed |
+| `walmart_get_return_count` | HTTP 404 | Compute client-side from `walmart_get_all_returns`, group by `status` |
+| `walmart_get_shipping_settings` | HTTP 404 | Check Seller Center settings UI manually |
+
+### Requires seller-program enrollment
+
+| Tool group | Requires |
+| --- | --- |
+| `walmart_*_repricer_*` | Walmart Repricer enrollment (Pro Seller badge usually required) |
+| `walmart_ad_*` (25 tools) | Walmart Connect — set `WALMART_AD_CONSUMER_ID` + `WALMART_AD_PRIVATE_KEY` |
+| `walmart_*_wfs_*` / `walmart_create_inbound_order` / `walmart_get_fulfillment_centers` etc. | Walmart Fulfillment Services (WFS) enrollment |
+
+### Behavior to be aware of
+
+| Tool | Note |
+| --- | --- |
+| `walmart_get_wfs_returns` | Sends the documented `GET /v3/returns?isWFSEnabled=Y` call. For sellers **without** WFS enrollment, Walmart returns the unfiltered return set (same data as `walmart_get_all_returns`). Upstream behavior, not an MCP defect. |
+
+### Region restrictions
+
+Walmart's Insights API (which `walmart_get_listing_quality` is built on) is
+US-Marketplace exclusive. Setting `WALMART_MARKET=mx|ca|cl` will surface a
+Walmart 404 on these calls; switch back to `us` to use them.
+
+If you hit something that is not on this list, open an issue with the tool
+name, the arguments, and the full error response (`walmart-mcp diagnose
+--export` produces a JSON dump suited for attachments).
+
+## Contributing
+
+PRs welcome. Before opening:
+
+1. `npm run typecheck && npm run test:run && npm run build` must all pass.
+2. New tools should follow the strict-zod-schema pattern in
+   `src/tools/definitions/<module>.ts`. The dispatcher (`src/tools/index.ts`)
+   re-parses args through the schema before calling the API layer.
+3. Walmart-side regressions belong in `src/utils/known-issues.ts` with a
+   matching workaround hint — keep this file aligned with the README "Known
+   Issues" section.
+
+## License
+
+MIT

package/build/api/advertising/ad-client.d.ts

@@ -0,0 +1,24 @@
+import { type WalmartConfig } from '../../config/environment.js';
+export declare class WalmartAdClient {
+    private config;
+    private http;
+    private accessToken;
+    private tokenExpiry;
+    private rateLimiter;
+    constructor(config: WalmartConfig);
+    /**
+     * Serialize request params into a query string deterministically (insertion
+     * order, scalars and arrays). Used to embed params into the request URL so
+     * the signed URL is byte-for-byte identical to what is actually sent —
+     * Walmart Connect validates the signature against the full request URL,
+     * including the query string.
+     */
+    private serializeParams;
+    private generateSignature;
+    private getAccessToken;
+    private setupInterceptors;
+    get<T = unknown>(endpoint: string, params?: object): Promise<T>;
+    post<T = unknown>(endpoint: string, data?: object): Promise<T>;
+    put<T = unknown>(endpoint: string, data?: object): Promise<T>;
+    delete<T = unknown>(endpoint: string, params?: object): Promise<T>;
+}