asin-check/README.md

asin-check

Amazon product analysis and lead finder agent. Reads product leads from a CSV/XLSX file, enriches them with Keepa pricing and sales data, caches results in Redis, and runs each product through a local LLM to get an FBA/FBM/SKIP verdict.

Requirements

• Bun runtime
• Redis (local or Docker)
• LM Studio running locally with a model loaded
• Keepa API key (keepa.com)

Setup

bun install
cp .env.example .env
# Edit .env and set your KEEPA_API_KEY

Usage

bun run src/index.ts <input.csv|xlsx> [--out results.csv]

Examples:

bun run src/index.ts leads.xlsx
bun run src/index.ts leads.csv --out results.xlsx

Input file format

Accepts .csv or .xlsx files. Column names are matched case-insensitively. Required column:

Column	Aliases
ASIN	—

Optional but recommended:

Column	Aliases
Product Name	Name, Title
Unit Cost	Cost, Price, Buy Cost
Brand	—
Category	—
Amazon Rank	Amazon Rank, BSR, Sales Rank
FBA NET	—
Gross Profit $	Gross Profit
Gross Profit %	—
MOQ	Min Order Qty
MOQ Cost	—
Total Qty Avail	Qty Available
Link	URL, Source

Pipeline

1. Read — parse input file, validate ASINs
2. Cache check — look up each ASIN in Redis (24h TTL by default)
3. Keepa fetch — batch all uncached ASINs in a single API call (up to 100 per request)
4. Enrich — combine Keepa data with spreadsheet data and SP-API fee estimates
5. LLM analysis — send batches of 5 products to LM Studio for FBA/FBM/SKIP verdict
6. Output — print results table to console, optionally write CSV/XLSX

Output columns

ASIN, Name, Brand, Category, Unit Cost, Current Price, Avg Price 90d, Sales Rank, Rank Avg 90d, Sellers, Monthly Sold, Rank Drops 30d, Rank Drops 90d, FBA Net (sheet), Gross Profit $, Gross Profit %, MOQ, MOQ Cost, Qty Available, FBA Fee, FBM Fee, Referral %, Verdict, Confidence, Reasoning

Environment variables

Variable	Default	Description
KEEPA_API_KEY	—	Required. Keepa API key
REDIS_URL	redis://localhost:6379	Redis connection URL
LLM_URL	http://localhost:1234/v1	LM Studio API base URL
LLM_MODEL	default	Model name to pass to LM Studio
CACHE_TTL	86400	Redis cache TTL in seconds

Notes

• Keepa rate limiting: The client reads tokensLeft and refillRate from each API response and waits automatically when tokens are exhausted. With a Pro subscription (1 token/min), all 100 ASINs in a batch cost 1 token.
• Redis is optional: If Redis is unavailable the tool runs without caching — every run re-fetches from Keepa.
• SP-API: Fee data is currently stubbed with estimates. The src/sp-api.ts module has TODO comments marking where real LWA OAuth + fee endpoint calls should go.