Skill: mikehankk/amazon-search (version 0.1.1)

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


Security scan verdicts — ClawScan: suspicious | static analysis: suspicious | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)