pangolinfo-amazon-scraper

Scrape Amazon product data using Pangolin APIs. Use this skill when the user wants to: look up Amazon products by ASIN, search Amazon by keyword, check bestsellers/new releases, get product reviews or pricing, compare products across Amazon regions, browse categories, or research sellers. Requires PANGOLIN_EMAIL + PANGOLIN_PASSWORD env vars (or PANGOLIN_API_KEY).

# Pangolinfo Amazon Scraper

Scrape Amazon product data via Pangolin's structured APIs. Returns parsed JSON with product details, search results, rankings, reviews, and more across 13 Amazon regions.

## When to Use This Skill

Activate this skill when the user's intent matches any of these patterns:

| Intent (English) | Intent (Chinese) | Action |
|---|---|---|
| Look up an Amazon product / ASIN | 查一下亚马逊上的这个商品 / ASIN | Product detail lookup |
| Search Amazon for a keyword | 在亚马逊搜索关键词 | Keyword search |
| Show bestsellers in a category | 看看某个类目的畅销榜 | Bestsellers |
| Show new releases | 看看最新上架的商品 | New releases |
| Browse a category on Amazon | 浏览亚马逊某个分类 | Category products |
| Find products from a seller | 查看某个卖家的商品 | Seller products |
| Get reviews for a product | 看看这个产品的评论 | Product reviews |
| Compare prices across regions | 对比不同国家亚马逊的价格 | Multi-region lookup |
| Check seller/variant options | 查看其他卖家选项 | Follow seller |

**Keywords that trigger this skill:** Amazon, ASIN, B0-prefixed codes, product reviews, bestseller, new release, Amazon category, Amazon seller, amz_us/amz_uk/etc., product detail, Amazon search, price comparison across Amazon sites.

## Prerequisites

### Required

- **Python 3.8+** (uses only the standard library -- zero external dependencies)
- **Pangolin account** at [pangolinfo.com](https://www.pangolinfo.com)
- **Environment variables** (one of the following):
  - `PANGOLIN_API_KEY` -- API key (skips login), OR
  - `PANGOLIN_EMAIL` + `PANGOLIN_PASSWORD` -- auto-login with caching

### macOS SSL Certificate Fix

On macOS, Python may fail with `CERTIFICATE_VERIFY_FAILED` because it ships without root certificates by default.

**Symptoms:** The script exits with error code `SSL_CERT`.

**Solutions (pick one):**

1. Run the certificate installer bundled with Python:
   ```bash
   /Applications/Python\ 3.x/Install\ Certificates.command
   ```
   (Replace `3.x` with your Python version, e.g., `3.11`)

2. Set `SSL_CERT_FILE` from the `certifi` package:
   ```bash
   pip3 install certifi
   export SSL_CERT_FILE=$(python3 -c "import certifi; print(certifi.where())")
   ```

3. Add the export to your shell profile (`~/.zshrc` or `~/.bashrc`) so it persists.

## First-Time Setup Guide

When a user tries to use this skill and authentication fails (error code `MISSING_ENV`), **do not just repeat the error hint**. Instead, walk the user through the full setup process interactively:

### Step 1: Explain what's needed

Tell the user (in their language):

> To use this skill, you need a Pangolin API account. Pangolin provides Amazon product data scraping through its APIs.
>
> 使用本技能需要 Pangolin API 账号。Pangolin 提供亚马逊商品数据抓取的 API 服务。

### Step 2: Guide registration

> 1. Go to [pangolinfo.com](https://www.pangolinfo.com) and create an account
> 2. After login, find your API Key in the dashboard
>
> 1. 访问 [pangolinfo.com](https://www.pangolinfo.com) 注册账号
> 2. 登录后在控制台找到你的 API Key

### Step 3: Collect credentials and authenticate automatically

When the user provides their credentials, **you (the AI agent) should configure them securely**. The script will automatically cache the API key at `~/.pangolin_api_key` for all future calls.

**If user provides an API key (recommended):**
Write it directly to the cache file — avoids shell history entirely:
```bash
echo "<api_key>" > ~/.pangolin_api_key
chmod 600 ~/.pangolin_api_key 2>/dev/null
python3 scripts/pangolin.py --auth-only
```

**If user provides email + password:**
Set env vars in the session and clean up after auth:
```bash
export PANGOLIN_EMAIL="user@example.com"
export PANGOLIN_PASSWORD="their-password"
python3 scripts/pangolin.py --auth-only
unset PANGOLIN_EMAIL PANGOLIN_PASSWORD
```

This avoids passwords appearing in shell history (unlike inline `VAR=x command` syntax) and cleans up credentials after the API key is cached.

Both methods cache the API key automatically. After this one-time setup, **no environment variables are needed** — all future calls will use the cached API key at `~/.pangolin_api_key`.

### Step 4: Confirm and proceed

After auth returns `"success": true`:
1. Tell the user: "认证成功！API Key 已自动缓存，后续使用无需再次输入。" / "Authentication successful! API Key cached — no need to enter credentials again."
2. Immediately retry their original request.

### Important

- **The user only needs to provide credentials ONCE** — the script caches the API key permanently at `~/.pangolin_api_key`
- Do not ask the user to manually edit `.bashrc` or `.zshrc` — the script handles persistence automatically
- If the user doesn't have an account yet, explain Pangolin's credit system (1 credit per Amazon json request, 5 credits per review page) and direct them to [pangolinfo.com](https://www.pangolinfo.com)
- If auth succeeds but credits are exhausted (error code `2001`), tell the user to top up at pangolinfo.com
- The API key is permanent and does not expire unless the account is deactivated

## Script Execution

The script is located at `scripts/pangolin.py` relative to this skill's root directory.

**Path resolution:** When invoking the script, resolve the absolute path from the skill directory. For example, if this skill is installed at `/path/to/pangolinfo-amazon-scraper/`:

```bash
python3 /path/to/pangolinfo-amazon-scraper/scripts/pangolin.py --content B0DYTF8L2W --mode amazon --site amz_us
```

## Intent-to-Command Mapping

### 1. Product Detail by ASIN

User says: "Look up B0DYTF8L2W on Amazon" / "查一下 B0DYTF8L2W 这个产品"

```bash
python3 scripts/pangolin.py --content B0DYTF8L2W --mode amazon --site amz_us
# Or using the --asin shortcut:
python3 scripts/pangolin.py --asin B0DYTF8L2W --site amz_us
```

The script auto-detects 10-character alphanumeric codes as ASINs and selects `amzProductDetail`. The `--asin` flag is a convenience shortcut that sets `--content` and defaults to `amzProductDetail` parser automatically.

### 2. Keyword Search

User says: "Search Amazon for wireless mouse" / "在亚马逊搜索无线鼠标"

```bash
python3 scripts/pangolin.py --q "wireless mouse" --mode amazon --site amz_us
```

Non-ASIN text auto-selects `amzKeyword` parser.

### 3. Bestsellers

User says: "Show me electronics bestsellers" / "看看电子产品畅销榜"

```bash
python3 scripts/pangolin.py --content "electronics" --mode amazon --parser amzBestSellers --site amz_us
```

### 4. New Releases

User says: "What's new in toys on Amazon?" / "亚马逊玩具类有什么新品？"

```bash
python3 scripts/pangolin.py --content "toys" --mode amazon --parser amzNewReleases --site amz_us
```

### 5. Category Products

User says: "Browse category 172282 on Amazon" / "浏览亚马逊分类 172282"

```bash
python3 scripts/pangolin.py --content "172282" --mode amazon --parser amzProductOfCategory --site amz_us
```

### 6. Seller Products

User says: "Show products from seller A1B2C3D4E5" / "查看卖家 A1B2C3D4E5 的商品"

```bash
python3 scripts/pangolin.py --content "A1B2C3D4E5" --mode amazon --parser amzProductOfSeller --site amz_us
```

### 7. Follow Seller (Variant / Seller Options)

User says: "Show other seller options for B0G4QPYK4Z" / "查看 B0G4QPYK4Z 的其他卖家选项"

```bash
python3 scripts/pangolin.py --asin B0G4QPYK4Z --parser amzFollowSeller --site amz_us
```

Uses a dedicated API endpoint (`/api/v1/scrape/follow-seller`). Returns variant options including price, delivery, fulfillment, and seller info for the given ASIN.

### 8. Product Reviews

User says: "Get critical reviews for B00163U4LK" / "看看 B00163U4LK 的差评"

```bash
python3 scripts/pangolin.py --content B00163U4LK --mode review --site amz_us --filter-star critical
```

**Star filter mapping:**

| User says (EN) | User says (CN) | `--filter-star` value |
|---|---|---|
| all reviews | 所有评论 | `all_stars` |
| 5-star / excellent | 五星 / 好评 | `five_star` |
| 4-star | 四星 | `four_star` |
| 3-star | 三星 | `three_star` |
| 2-star | 两星 | `two_star`