# 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](https://bun.com) runtime
- Redis (local or Docker)
- [LM Studio](https://lmstudio.ai) running locally with a model loaded
- Keepa API key ([keepa.com](https://keepa.com))
- Amazon SP-API private app credentials (LWA + refresh token + IAM)

## Setup

```bash
bun install
cp .env.example .env
# Edit .env and set your KEEPA_API_KEY and SP-API credentials
```

## Usage

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

Examples:

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

Quick SP-API connectivity tests:

```bash
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

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                  |

Lead-list format aliases (supported):

| Column            | Aliases                                    |
| ----------------- | ------------------------------------------ |
| Name              | Product Name, Title, Product Title         |
| ASIN Link         | ASIN URL, Amazon Link                      |
| Source URL        | Source Link, Supplier URL                  |
| 90 Day Average    | 90-day Average, Avg Price 90d, 90d Average |
| Cost              | Unit Cost, Buy Cost, Price                 |
| Selling Price     | Sale Price, Sell Price                     |
| Net Profit        | Gross Profit                               |
| ROI               | Gross Profit %, Return on Investment       |
| Supplier          | Vendor                                     |
| Promo/Coupon Code | Promo Code, Coupon Code                    |
| Notes             | Note                                       |
| Date              | Lead Date                                  |

Numeric parsing accepts plain numbers as well as formatted values like `$12.50`, `1,209.60`, and `27.5%`.

## Pipeline

1. **Read** — parse input file, validate ASINs
2. **Cache check** — look up each ASIN in Redis (24h TTL by default)
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

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                                             |
| `SP_API_CLIENT_ID`      | —                          | LWA app client id from Solution Provider Portal                         |
| `SP_API_CLIENT_SECRET`  | —                          | LWA app client secret from Solution Provider Portal                     |
| `SP_API_REFRESH_TOKEN`  | —                          | Refresh token from self-authorization                                   |
| `SP_API_REGION`         | `na`                       | SP-API endpoint region (`na`, `eu`, `fe`; `us` is accepted as `na`)     |
| `SP_API_MARKETPLACE_ID` | `ATVPDKIKX0DER`            | Marketplace id used for pricing and fee calls (default: US)             |
| `SP_API_SELLER_ID`      | —                          | Seller ID used for listing restrictions eligibility checks              |
| `SP_API_USE_SANDBOX`    | `false`                    | Enable SP-API sandbox mode (`true`/`false`)                             |
| `AWS_ACCESS_KEY_ID`     | —                          | AWS credentials for SigV4 signing (required in most private app setups) |
| `AWS_SECRET_ACCESS_KEY` | —                          | AWS credentials for SigV4 signing                                       |
| `AWS_SESSION_TOKEN`     | —                          | Optional session token when using STS credentials                       |
| `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

- **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` 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.