sellersprite-rpa

Unified skill covering the 5 core sellersprite Amazon data-analysis modules:

Merged from the 5 original per-skill installs (kept as backup under
.claude/skills/sellersprite-<section>/ until retired). Transport is
BrowserSkill (bsk) — see references/environment.md.

Requirements

• BrowserSkill (bsk): CLI on PATH + browser extension connected — bsk status must show browsers connected >= 1
• sellersprite login in that same browser. Login-expiry signal: v2 sections (keywords/markets) redirect to /w/user/login; v3 APIs may still return data anonymously — do not treat v3 success as proof of login.
• Python 3.10+ (no third-party packages)

Quick start

CLI="python .claude/skills/sellersprite-rpa/scripts/sellersprite_rpa.py"

# products — top 100 US ASINs (5 pages × 20)
$CLI fetch --section products --station US --pages 5 --out data/us_top100.csv

# keywords — "flashlight" across 3 stations
$CLI fetch --section keywords --station US,JP,GB --keyword flashlight --pages 1 \
    --out data/keywords_by_station.csv

# markets — sub-markets matching "led"
$CLI fetch --section markets --station US --keyword led --out data/markets.csv

# aba — keyword rank (or ASIN reverse via --query B0XXXX)
$CLI fetch --section aba --station US --query "yoga mat" --pages 1 --out data/aba.csv

# competitors — exactly one of --keyword/--brand/--seller/--asin
$CLI fetch --section competitors --station US --keyword "yoga mat" --pages 1 \
    --out data/comp.csv

# analyze — report per section
$CLI analyze --section aba --input data/aba.csv --out-md reports/aba.md

Multi-station runs write one CSV per station (<stem>_<STATION>.csv) plus the
combined CSV. All fetches accept --session (default sellersprite-rpa).

Station vocabulary

10 Amazon marketplaces: US 美国 / JP 日本 / GB 英国 / DE 德国 / FR 法国 / IT 意大利 / ES 西班牙 / CA 加拿大 / IN 印度 / MX 墨西哥.

Market-code quirk per section (see references/api_notes_*.md): products uses
the 2-letter station code as body market; aba uses COM for US;
competitors uses 2-letter codes; keywords/markets URLs need marketId ints
(mapped automatically).

Architecture

scripts/
├─ sellersprite_rpa.py   # single-entry CLI: fetch / analyze (--section)
├─ bridge_browserskill.py# bsk transport adapter (call/evaluate/session_stop)
├─ common.py             # shared helpers: page fetch, station click, CSV writer
├─ core_api.py           # API engine: ensure→post_json loop→dedupe→flatten
├─ core_dom.py           # DOM engine: keywords URL-pagination / markets form-submit
├─ sections.py           # config registry: URLs, build_body/parse_row (verbatim)
├─ analyze.py            # report dispatcher
└─ report_<section>.py   # 5 report generators (verbatim ports, run() entry)

Rule: engines read config from sections.py and never hardcode section
details; the parse/build/flatten functions are verbatim ports of the original
per-skill scripts — do not rewrite them casually.

Gotchas digest

1. Subscription modal pops on every v3 page load — ensure_v3_page() auto-dismisses via .ant-modal-close.
2. Free-tier masking: products caps amzUnit at 100k; keywords unmask top 50 only; aba returns null items beyond page 1; competitors returns ~20 unique ASINs (page 2+ repeats, deduped automatically).
3. v2 station switching needs the UI click — URL station= param is ignored; click_station_button() handles it (matches label via startsWith).
4. SPA/HTML latency: engines sleep after navigation (products/aba/comp ~6s total; keywords 5s/page; markets 6s+6s). If you see 0 rows, suspect "too fast" before selectors.
5. GB pagination bug (products): page 2 may repeat page 1 — report_products.py dedupes by (market, ASIN).
6. Keyword index is station-specific for markets: flashlight returns 0 rows on JP/GB — use globally-recognized terms (led, phone, yoga) for multi-station runs.
7. CSV encoding: outputs are utf-8-sig (BOM). Read with encoding="utf-8-sig" on Windows.

See also

• references/environment.md — bsk transport, Windows/bash/UTF-8 quirks (read before writing shell commands or evaluate JS)
• references/api_notes_<section>.md — full API/page contracts per section
• references/analysis_recipe_<section>.md — report template structures
• references/category_nodes.md — Amazon Browse Node IDs for products --node-id