feat: enhance README with updated SP-API connectivity tests and sellability optimization details

README.md

@@ -31,12 +31,12 @@ bun run src/index.ts leads.xlsx
 bun run src/index.ts leads.csv --out results.xlsx
 ```
 
-Quick SP-API connectivity test:
+Quick SP-API connectivity tests:
 
 ```bash
-bun run src/sp-test.ts
-bun run src/sp-test.ts B07SN9BHVV
-bun run src/sp-test.ts --sellability B07SN9BHVV
+bun run src/sp-test.ts               # Auth + sellers endpoint
+bun run src/sp-test.ts B07SN9BHVV    # Auth + sellers endpoint + pricing offer check
+bun run src/sp-test.ts --sellability B07SN9BHVV  # Standalone sellability check
 ```
 
 ## Input file format
@@ -87,10 +87,11 @@ Numeric parsing accepts plain numbers as well as formatted values like `$12.50`,
 
 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
+3. **Sellability gate** — check all uncached ASINs against SP-API `getListingsRestrictions` (concurrency: 5 workers); immediately skip ASINs with status `not_available` and `canSell=false` (no Keepa/fees wasted)
+4. **Keepa fetch** — batch the sellable (uncached) ASINs in a single API call (up to 100 per request)
+5. **Enrich** — fetch SP-API pricing + FBA/FBM fees for sellable ASINs; combine with Keepa data and spreadsheet data
+6. **LLM analysis** — send batches of 5 sellable products to LM Studio for FBA/FBM/SKIP verdict; skipped ASINs get auto-SKIP verdict (confidence 100) and bypass LLM entirely
+7. **Output** — print results table to console (includes all ASINs), optionally write CSV/XLSX
 
 ## Output columns
 
@@ -118,7 +119,11 @@ ASIN, Name, Brand, Category, Unit Cost, Current Price, Avg Price 90d, Sales Rank
 
 ## Notes
 
+- **Sellability-first optimization**: SP-API `getListingsRestrictions` is checked first to filter out unsellable items before consuming Keepa tokens or running full SP-API pricing/fees queries. This saves API calls and reduces runtime for large lead lists.
+- **SP-API concurrency**: `fetchSellabilityBatch` limits concurrent requests to 5 workers to avoid 429 throttling. Pricing+fees fetches also use 5 concurrent workers.
+- **No batch endpoint**: Amazon SP-API does not provide batch endpoints for `getListingsRestrictions` or `getMyFeesEstimate*`. Concurrency limiting with the library's built-in `auto_request_throttled` safety net prevents overwhelming the API.
 - **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**: `src/sp-api.ts` now uses `amazon-sp-api` to fetch offer pricing and FBA/FBM fee estimates. If SP-API credentials are missing or a call fails, the tool falls back to conservative fee defaults and keeps processing.
+- **SP-API**: `src/sp-api.ts` provides `fetchSellability`, `fetchSellabilityBatch`, and `fetchSpApiPricingAndFees` functions. If SP-API credentials are missing or a call fails, the tool falls back to conservative fee defaults and keeps processing.
+- **Skipped ASINs**: Products with `not_available` sellability status and `canSell=false` appear in output with verdict `SKIP`, confidence 100, and reasoning from the sellability check. They do not consume LLM inference.
 - **Sandbox vs production**: When `SP_API_USE_SANDBOX=true`, production ASIN calls can be denied. Use sandbox-compatible test data or set it to `false` for live marketplace connectivity.