asin-check/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Default to using Bun instead of Node.js.

• Use bun <file> instead of node <file> or ts-node <file>
• Use bun test instead of jest or vitest
• Use bun install instead of npm install or yarn install
• Use bun run <script> instead of npm run <script>
• Bun automatically loads .env, so don't use dotenv.

APIs

• bun:sqlite for SQLite. Don't use better-sqlite3.
• Bun.redis for Redis. Don't use ioredis.
• Prefer Bun.file over node:fs's readFile/writeFile.
• Bun.$\cmd`` instead of execa.

Commands

# Run all tests
bun test

# Run a single test file
bun test src/supplier-scoring.test.ts

# Type-check (no emit)
./node_modules/.bin/tsc --noEmit

# ASIN lead-list pipeline (LLM-based)
bun run src/index.ts input/leads.xlsx --out output/results.xlsx

# Supplier UPC pipeline (deterministic)
bun run upc-file --input input/supplier.xlsx --out output/supplier_ranked.xlsx

# Category discovery pipelines
bun run bestsellers
bun run monthly-sold
bun run mid-range

# Web API server
bun run start:web      # http://localhost:3000

# SP-API connectivity tests
bun run src/sp-test.ts
bun run src/sp-test.ts B07SN9BHVV
bun run src/sp-test.ts --sellability B07SN9BHVV

Architecture

Two distinct analysis pipelines share infrastructure (Keepa, SP-API, Redis, SQLite) but diverge in how they produce verdicts.

ASIN Lead-list Pipeline (src/index.ts → src/analysis-pipeline.ts)

For spreadsheets containing known ASINs. Verdict is LLM-based (FBA/FBM/SKIP via LM Studio).

Flow: reader.ts parse → Redis cache check → sp-api.ts sellability gate (5 concurrent workers) → keepa.ts batch enrichment → sp-api.ts pricing + FBA fees (5 concurrent workers) → llm.ts batched analysis (5 products/batch) → writer.ts XLSX + SQLite.

Supplier UPC Pipeline (src/upc-file-analysis.ts)

For supplier price lists containing UPC/EAN values. Verdict is deterministic (BUY/WATCH/SKIP); never calls LM Studio.

Flow: upc-file-reader.ts streaming parse (.xlsx) or row-window parse (.xls) → SP-API catalog UPC lookup first, Keepa UPC lookup as fallback → keepa.ts demand enrichment → sp-api.ts sellability + FBA fees → supplier-scoring.ts deterministic score → supplier-export.ts Excel workbook (Ranked Leads, Skipped, Summary sheets) + SQLite.

UPC resolution priority: SP-API catalog lookup → Keepa fallback (for no-match or request failure only).

Category Pipelines

bestsellers-by-category.ts, top-monthly-sold-by-category.ts, mid-range-sellers-by-category.ts — Keepa category browsing → SP-API sellability gate → LLM verdict. Each saves results to SQLite. Mid-range applies configurable filters (monthly sold, price, seller count, Amazon buy box share).

Shared Infrastructure

Module	Role
src/types.ts	All shared interfaces (ProductRecord, KeepaData, SpApiData, SupplierScore, etc.)
src/config.ts	Env var loading via Bun.env
src/keepa.ts	Keepa API: batch ASIN fetch, UPC lookup, auto rate-limiting on token exhaustion
src/sp-api.ts	SP-API: sellability (getListingsRestrictions), pricing+fees, UPC catalog lookup
src/cache.ts	Redis caching (24h TTL for lead-list; 12h for mid-range)
src/database.ts	SQLite runs + results tables; auto-creates db/results.db
src/server.ts	Bun HTTP server exposing REST endpoints for both pipelines

File Layout

• input/ — source spreadsheets (git-ignored)
• output/ — generated workbooks (git-ignored)
• db/ — SQLite files (git-ignored)
• src/ — all source and test files

Project Rules

• Keep the ASIN lead-list and category flows compatible with their current LLM-based FBA/FBM/SKIP analysis.
• The supplier UPC pipeline must not call LM Studio.
• Supplier UPC files resolve UPC/EAN through SP-API catalog lookup first; Keepa UPC lookup is fallback only (no-match or request-failure cases).
• Supplier workbook output must keep Ranked Leads, Skipped, and Summary sheets.
• When changing UPC supplier behavior, cover SP-API UPC parsing, deterministic scoring, and workbook export with bun test.