ebayDeepScan/README.md

eBay MPN Matcher

Multi-step pipeline: eBay search → exact MPN match → AI match → price comparison.

Setup

npm install
cp .env.example .env
# Fill in EBAY_CLIENT_ID, EBAY_CLIENT_SECRET, OPENAI_API_KEY

Files required

File	Description
keywords.txt	One search keyword per line
prices.xlsx	Col A: partnumber, Col B: price (USD)
system_prompt.txt	AI system prompt for this product profile

Run

node index.js

Output saved to ./output/:

• results_<runId>.xlsx — full results with PASS/FAIL
• results_<runId>.json — same data as JSON
• run_<runId>.log — full run log with timing
• ai_cache.json — cached AI matches (reused on next run)

Flow

keywords.txt
    │
    ▼ Step 1: eBay search (all keywords, dedup by URL item ID)
    │
    ▼ Step 2: Exact MPN match (regex + normalized)
    │         ├─ matched   → list A
    │         └─ unmatched → Step 3
    │
    ▼ Step 3: AI match (gpt-4o-mini, batch 40 items)
    │         ├─ GOOD_MATCH / VARIANT_MISMATCH → list B
    │         ├─ INSUFFICIENT_DATA → fetch detail → retry AI
    │         └─ UNRELATED_PRODUCT → skip
    │
    ▼ Step 4: Merge A+B → compare price → PASS/FAIL → export

Match methods in output

Method	Description
exact	Regex found MPN in title/specs
ai_exact	AI matched with GOOD_MATCH
ai_variant	AI matched with VARIANT_MISMATCH
ai_detail	AI matched after fetching detail page
ai_cached	From previous run cache

Config (.env)

Key	Default	Description
AI_BATCH_SIZE	40	Listings per AI request
AI_CONFIDENCE_THRESHOLD	50	Min confidence to count as PASS
OPENAI_MODEL	gpt-4o-mini	OpenAI model
EBAY_MARKETPLACE	EBAY_US	eBay marketplace ID

Adding a new product profile

1. Create new keywords_<profile>.txt
2. Create new system_prompt_<profile>.txt explaining the product domain
3. Update .env to point to new files
4. Run — AI cache is per-itemId so it auto-separates