ecommerce-price-watcher

跟踪电子商务网站上的产品价格，并对报价或达到目标价格发出警报。当用户想要监控一个或多个产品 URL 或商品查询、比较当前价格与之前的价格、检测折扣并生成包含产品名称、旧/新价格、下降百分比和直接链接的警报摘要时使用。

# Ecommerce Price Watcher

Monitor product URLs, keep price history, detect offers, and output alert-ready JSON.

## Quick start

Use `scripts/price_watch.py`.

```bash
# URL mode
python3 skills/ecommerce-price-watcher/scripts/price_watch.py add \
  --url "https://example.com/product" \
  --target-price 399990 \
  --currency CLP

# Item mode (discover URLs from query)
python3 skills/ecommerce-price-watcher/scripts/price_watch.py add-item \
  --query "iPhone 13 128GB Chile" \
  --target-price 349990 \
  --currency CLP \
  --trusted-only \
  --max-results 5

python3 skills/ecommerce-price-watcher/scripts/price_watch.py check --all
```

## Commands

- `add`: add a single product URL
- `add-item`: discover product URLs from an item query, then add watches
- `list`: list watched products
- `check --id <id>`: check one product now
- `check --all`: check all products now
- `remove --id <id>`: delete watcher
- `history --id <id>`: print full price history

## Alert behavior

A check produces alerts when at least one condition matches:

1. `price_drop`: current price < previous price
2. `target_hit`: current price <= target price

Alert payload includes:
- product id
- title
- old/new price
- drop percent (when available)
- URL
- timestamp

## Item-query mode details

`add-item` uses a lightweight search discovery flow to find candidate product links.

- `--trusted-only` restricts discovered URLs to a curated trusted domain list.
- `--max-results` controls how many links are added.
- Duplicate URLs are skipped safely.

This gives users natural language entry ("track iPhone 13 128GB") instead of forcing direct URLs.

## Parsing strategy

Use a layered parser:
1. JSON-LD `offers.price`
2. Open Graph/meta price fields
3. Generic HTML regex fallback

When multiple prices are found, choose the lowest positive value as the current offer candidate.

## Security standards

- Accept only `http`/`https` URLs.
- Enforce request timeout.
- Enforce response body size cap.
- Do not execute remote JavaScript.
- Store no API keys/tokens in watcher data.
- Treat all page content as untrusted.
- Return structured JSON for safe downstream automation.

## Limits and operational notes

- Some stores block bot-like requests (403). This is expected on certain sites.
- Price extraction is best-effort and may need store-specific adapters over time.
- For production alerting, run `check --all` on schedule and forward only non-empty `alerts`.

## Suggested scheduled usage

Run every 30–120 minutes via cron, then send each alert to Telegram/WhatsApp/Discord.

---

## 中文说明

# Ecommerce Price Watcher

监控产品 URL，保存价格历史，检测优惠，并输出可用于警报的 JSON。

## 快速开始

使用 `scripts/price_watch.py`。

```bash
# URL mode
python3 skills/ecommerce-price-watcher/scripts/price_watch.py add \
  --url "https://example.com/product" \
  --target-price 399990 \
  --currency CLP

# Item mode (discover URLs from query)
python3 skills/ecommerce-price-watcher/scripts/price_watch.py add-item \
  --query "iPhone 13 128GB Chile" \
  --target-price 349990 \
  --currency CLP \
  --trusted-only \
  --max-results 5

python3 skills/ecommerce-price-watcher/scripts/price_watch.py check --all
```

## 命令

- `add`：添加单个产品 URL
- `add-item`：根据商品查询发现产品 URL，然后添加监控
- `list`：列出受监控的产品
- `check --id <id>`：立即检查某个产品
- `check --all`：立即检查所有产品
- `remove --id <id>`：删除监控器
- `history --id <id>`：打印完整价格历史

## 警报行为

当满足至少一个条件时，一次检查会产生警报：

1. `price_drop`：当前价格 < 上次价格
2. `target_hit`：当前价格 <= 目标价格

警报负载包含：
- 产品 id
- 标题
- 旧/新价格
- 下降百分比（在可用时）
- URL
- 时间戳

## 商品查询模式详情

`add-item` 使用一个轻量级的搜索发现流程来查找候选产品链接。

- `--trusted-only` 将发现的 URL 限制在一份精选的受信任域名列表内。
- `--max-results` 控制添加的链接数量。
- 重复的 URL 会被安全地跳过。

这让用户可以使用自然语言进行录入（"track iPhone 13 128GB"），而不必强制提供直接 URL。

## 解析策略

使用分层解析器：
1. JSON-LD `offers.price`
2. Open Graph/meta 价格字段
3. 通用 HTML 正则回退方案

当找到多个价格时，选择最低的正值作为当前报价候选。

## 安全标准

- 仅接受 `http`/`https` URL。
- 强制请求超时。
- 强制响应体大小上限。
- 不执行远程 JavaScript。
- 不在监控数据中存储任何 API key/令牌。
- 将所有页面内容视为不可信。
- 返回结构化 JSON，以便下游安全地自动化处理。

## 限制与操作说明

- 部分商城会拦截类似机器人的请求（403）。这在某些站点上是预期的。
- 价格提取为尽力而为，随时间推移可能需要针对特定商城的适配器。
- 对于生产级警报，按计划运行 `check --all`，并仅转发非空的 `alerts`。

## 建议的定时使用方式

通过 cron 每 30–120 分钟运行一次，然后将每条警报发送到 Telegram/WhatsApp/Discord。