docs: price filtering schema adjustments

Signed-off-by: Dmytro Stanchiev <git@dmytros.dev>

docs/superpowers/plans/2026-04-30-ebay-dollar-price-inputs.md

@@ -0,0 +1,82 @@
+# Marketplace Dollar Price Inputs Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make public marketplace price inputs use dollars while preserving core scraper cent-based filtering.
+
+**Architecture:** API server owns HTTP query parsing and converts dollar amounts to cents before calling core. MCP server keeps forwarding numeric dollar values as query params. Core scraper internals remain unchanged because parsed listing prices already use cents. This applies to eBay `minPrice`/`maxPrice` and Kijiji `priceMin`/`priceMax`; Facebook exposes no price filter inputs.
+
+**Tech Stack:** Bun, TypeScript, `bun:test`, MCP JSON-RPC adapter, framework-free Bun HTTP routes.
+
+---
+
+### Task 1: API Dollar Parsing
+
+**Files:**
+- Modify: `packages/api-server/src/routes/helpers.ts`
+- Modify: `packages/api-server/src/routes/ebay.ts`
+- Modify: `packages/api-server/src/routes/kijiji.ts`
+- Test: `packages/api-server/test/routes.test.ts`
+
+- [ ] **Step 1: Add failing API route tests**
+
+Add tests proving eBay `minPrice=999.99` / `maxPrice=1000` and Kijiji `priceMin=999.99` / `priceMax=1000` are forwarded to core as `99999` and `100000` cents. Add validation tests for empty, whitespace, negative, hex, mixed text, and malformed decimal price values.
+
+Run: `bun test packages/api-server/test/routes.test.ts`
+
+Expected: new forwarding tests fail because route currently rejects decimals and forwards integer dollars unchanged.
+
+- [ ] **Step 2: Implement dollar parser helper**
+
+Add `parseDollarPriceParam(searchParams, name)` in `packages/api-server/src/routes/helpers.ts`. Accept `0`, `1000`, `999.99`, and `0.99`. Reject values that do not match `^\d+(?:\.\d{1,2})?$`. Convert to cents with `Math.round(Number(rawValue) * 100)`.
+
+- [ ] **Step 3: Use dollar parser in eBay route**
+
+Replace `parseNonNegativeIntegerParam` calls for eBay `minPrice`/`maxPrice` and Kijiji `priceMin`/`priceMax` with `parseDollarPriceParam`. Keep pagination/count params on integer parsing.
+
+- [ ] **Step 4: Verify API tests**
+
+Run: `bun test packages/api-server/test/routes.test.ts`
+
+Expected: all API route tests pass.
+
+### Task 2: MCP Schema Contract
+
+**Files:**
+- Modify: `packages/mcp-server/src/protocol/tools.ts`
+- Test: `packages/mcp-server/test/protocol.test.ts`
+
+- [ ] **Step 1: Add MCP schema/forwarding tests**
+
+Add tests that `search_ebay` describes `minPrice` and `maxPrice` as dollar filters and forwards numeric dollar values unchanged in API query params.
+
+Run: `bun test packages/mcp-server/test/protocol.test.ts`
+
+Expected: description test fails until schema text changes; forwarding behavior should already pass or reveal mapping gaps.
+
+- [ ] **Step 2: Update tool descriptions**
+
+Change eBay `minPrice` and Kijiji `priceMin` descriptions to `Minimum price in dollars`. Change eBay `maxPrice` and Kijiji `priceMax` descriptions to `Maximum price in dollars`.
+
+- [ ] **Step 3: Verify MCP tests**
+
+Run: `bun test packages/mcp-server/test/protocol.test.ts`
+
+Expected: all MCP protocol tests pass.
+
+### Task 3: Cross-Package Verification
+
+**Files:**
+- No additional edits expected.
+
+- [ ] **Step 1: Run relevant package tests**
+
+Run: `bun test packages/api-server/test packages/mcp-server/test`
+
+Expected: all tests pass.
+
+- [ ] **Step 2: Run CI**
+
+Run: `bun run ci`
+
+Expected: typecheck and Biome pass without changing lint config.