\r \r

Amazon Search Skill\r

Search Amazon for products matching a keyword query and return structured JSON results.\r \r

Prerequisites\r

\r Install Bun runtime:\r \r

curl -fsSL https://bun.sh/install | bash\r
```\r
\r
Install skill dependencies:\r
\r
```bash\r
cd skills/amazon-search\r
bun install\r
```\r
\r
Install Playwright browsers (required for Amazon search):\r
\r
```bash\r
cd skills/amazon-search/scripts\r
npm install\r
npx playwright install chromium\r
```\r
\r
## Cookie\r
\r
This skill uses **Playwright** to search Amazon directly in a headless browser. No manual cookie management is required.\r
\r
### Playwright Prerequisites\r
\r
Install npm dependencies and Playwright browsers:\r
\r
```bash\r
cd skills/amazon-search/scripts\r
npm install\r
npx playwright install chromium\r
```\r
\r
## Inputs\r
| Parameter       | Type | Description |\r
|-----------------|---|---|\r
| `keyword`         | string | Search keywords (e.g. `"t-shirt"`) |\r
| `proxy`         | string | Optional proxy URL. Can be set as argument value or via `--proxy` flag / `T2P_PROXY` env var. Supports HTTP/HTTPS and SOCKS5 proxies. |\r
| `price_min`    | number | Optional minimum price filter. Mapped to Amazon `low-price`. |\r
| `price_max`    | number | Optional maximum price filter. Mapped to Amazon `high-price`. |\r
| `--pages`      | number | Max number of pages to fetch (default: 1). Each page has ~20-60 results. |\r
| `--num-products` | number | Max number of products to fetch. Stops when limit is reached, even if more pages available. |\r
| `--incremental` | flag | Only output new results that haven't been cached before. |\r
| `--clear-cache` | flag | Clear cache for this keyword before searching. |\r
| `--output`      | string | Custom output directory for results (default: `results/`). |\r
| `--download`    | flag | Download product images after search using `@t2p/image-cache`. |\r
\r
## Output Format\r
Returns a JSON object containing search metadata and an array of Amazon product objects.\r
\r
Results are automatically saved to `results/\x3Ckeyword>_\x3Ctimestamp>_\x3Ccount>.json`.\r
\r
```json\r
{\r
  "keyword": "shirt",\r
  "timestamp": "2026-04-06T12:34:56.789Z",\r
  "count": 10,\r
  "items": [\r
    {\r
      "id_": "B09TPN9NJ6",\r
      "uuid": "418e2c7d-ccaa-4ca3-9d1b-6b4f3bd406b0",\r
      "original_image_url": "https://m.media-amazon.com/images/I/91YprRrDB4L._AC_UL960_FMwebp_QL65_.jpg",\r
      "title": "Amazon Essentials Men's Slim-Fit Crewneck T-Shirts, Short Sleeve",\r
      "item_page": "https://www.amazon.com/dp/B09TPN9NJ6",\r
      "rating": 4.4,\r
      "review_count": 1787,\r
      "price": "$19.99",\r
      "description": "Amazon Essentials Men's Slim-Fit Crewneck T-Shirts, Short Sleeve"\r
    }\r
  ]\r
}\r
```\r
\r
### Item Fields\r
\r
| Field | Type | Description |\r
|-------|------|-------------|\r
| `id_` | string | Amazon ASIN (Amazon Standard Identification Number) |\r
| `uuid` | string | Unique identifier from Amazon's data attributes |\r
| `original_image_url` | string | Product image URL (highest resolution from srcset) |\r
| `title` | string | Product title |\r
| `item_page` | string | Full URL to the product page |\r
| `rating` | number | Average rating (1-5) |\r
| `review_count` | number | Number of reviews |\r
| `price` | string | Price as displayed on Amazon (includes currency) |\r
| `description` | string | Product description (may be same as title if no separate description) |\r
\r
## Execution\r
\r
Use the script at `scripts/amazon_search.ts`.\r
\r
All TypeScript files must be run with **Bun**:\r
\r
```bash\r
# Simple search\r
bun run scripts/amazon_search.ts "shirt"\r
```\r
\r
### Configuration Tool\r
\r
Use `scripts/configure.ts` to generate environment variable commands and manage cache:\r
\r
```bash\r
# Generate proxy setting command (copy and run the output)\r
bun run scripts/configure.ts proxy "http://127.0.0.1:7890"\r
\r
# List cache files\r
bun run scripts/configure.ts listcache\r
\r
# Clear cache for specific keyword\r
bun run scripts/configure.ts clearcache "shirt"\r
\r
# Clear all caches\r
bun run scripts/configure.ts clearcache --all\r
```\r
\r
## Usage Notes\r
\r
- **Runtime**: All TypeScript files must be run with `bun run`\r
- **Search Method**: Uses **Playwright** to search Amazon directly in a headless browser (no manual cookie management needed)\r
- **Proxy Support**: Proxy is read from `T2P_PROXY` environment variable (or `--proxy` CLI flag). Supports both HTTP/HTTPS and SOCKS5 proxies (e.g., `socks5://127.0.0.1:1080`).\r
- **Cache & Deduplication**: Search results are cached to `resultscache/\x3CsanitizedQuery>_cache.md`. Each line is an ASIN/uuid used for deduplication.\r
- **Incremental Mode**: Use `--incremental` to output only items not present in the cache.\r
- **Clear Cache**: Use `--clear-cache` to delete this keyword cache before searching, or use `scripts/configure.ts clearcache`.\r
- **Custom Output**: Use `--output=/path/to/dir` to save results to a custom directory.\r
- **Download Images**: Use `--download` to automatically download product images using `@t2p/image-cache` after search completes.\r
\r
## Example\r
All commands use `bun run`:\r
\r
```bash\r
# Simple search\r
bun run scripts/amazon_search.ts "t-shirt"\r
\r
# Incremental search - only output new results not in cache\r
bun run scripts/amazon_search.ts "t-shirt" --incremental\r
\r
# Clear cache before searching\r
bun run scripts/amazon_search.ts "t-shirt" --clear-cache --incremental\r
\r
# Use proxy\r
bun run scripts/amazon_search.ts "t-shirt" --incremental --proxy "http://127.0.0.1:10809"\r
\r
# Multi-page search (fetch 2 pages, ~40-120 results)\r
bun run scripts/amazon_search.ts "t-shirt" --pages=2\r
\r
# Multi-page + incremental (only new items from all pages)\r
bun run scripts/amazon_search.ts "t-shirt" --pages=2 --incremental\r
\r
# Limit to specific number of products (stops early if limit reached)\r
bun run scripts/amazon_search.ts "t-shirt" --pages=5 --num-products=50\r
\r
# Specify custom output directory\r
bun run scripts/amazon_search.ts "t-shirt" --output=/path/to/custom/results\r
\r
# Download images after search\r
bun run scripts/amazon_search.ts "t-shirt" --download\r
\r
# Combined: search with download and custom output\r
bun run scripts/amazon_search.ts "t-shirt" --download --output=/path/to/results\r
```\r
\r
## Error Handling\r
| Situation | What to do |\r
|---|---|\r
| HTTP 4xx/5xx / Search blocked | Amazon may be rate-limiting; try again later with a different proxy, or wait before retrying |\r
| Parse errors / empty results | Page layout may have changed; try different keywords, pages, or filters |\r
| Playwright launch errors | Ensure Playwright browsers are installed: `cd scripts && npx playwright install chromium` |\r