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.redis for Redis. Don't use ioredis.
• Use Drizzle ORM with postgres driver for Postgres. Connection is in src/db/index.ts.
• 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/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

# Stalker pipeline
bun run stalker --input input/asins.xlsx

# 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

# Database migrations (Drizzle)
bun run db:generate
bun run db:migrate

Architecture

Two distinct analysis pipelines share infrastructure (Keepa, SP-API, Redis, Postgres) 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 → integrations/sp-api.ts sellability gate (5 concurrent workers) → integrations/keepa.ts batch enrichment → integrations/sp-api.ts pricing + FBA fees (5 concurrent workers) → integrations/llm.ts batched analysis (5 products/batch) → writer.ts XLSX + Postgres.

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

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

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

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

Category Pipelines

src/categories/ — Keepa category browsing → SP-API sellability gate → LLM verdict. Each saves results to Postgres. Mid-range applies configurable filters (monthly sold, price, seller count, Amazon buy box share).

Stalker Pipeline (src/stalker/stalker.ts)

Tracks competitor sellers across ASINs. Fetches storefronts, checks sellability of inventory items, and persists matched seller data to Postgres.

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/db/index.ts	Drizzle Postgres connection (shared pool)
src/db/schema.ts	Drizzle schema for all tables
src/db/persistence.ts	Product, observation, unified run-item, UPC resolution, and revision persistence
src/integrations/keepa.ts	Keepa API: batch ASIN fetch, UPC lookup, auto rate-limiting
src/integrations/sp-api.ts	SP-API: sellability, pricing+fees, UPC catalog lookup
src/integrations/cache.ts	Redis caching (24h TTL for lead-list; 12h for mid-range)
src/integrations/llm.ts	LLM integration (LM Studio / Claude)
src/server.ts	Bun HTTP server exposing REST endpoints for both pipelines

File Layout

• src/integrations/ — external API clients (Keepa, SP-API, Redis cache, LLM, SearXNG)
• src/categories/ — category discovery pipelines
• src/stalker/ — competitor seller tracking pipeline
• src/supplier/ — supplier UPC analysis pipeline
• src/db/ — Drizzle schema and connection
• input/ — source spreadsheets (git-ignored)
• output/ — generated workbooks (git-ignored)

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.
• Treat products.asin as the canonical normalized product identity; UPC values belong only in identifier and resolution records.
• Store time-varying data in observations or revisions and retain run history rather than overwriting prior analysis.
• When changing UPC supplier behavior, cover SP-API UPC parsing, deterministic scoring, and workbook export with bun test.