herosms-api

name	herosms-api
description	Use for HeroSMS virtual-number API operations in D:\reverse_ENV, including API-key setup, balance checks, country/service/price lookup, activation offers, buying a number with a price ceiling, polling an OTP, reading SMS history, and completing or cancelling an activation. Trigger for HeroSMS、hero-sms、接码 API、购买号码、收验证码、查询接码库存或迁移 SMS-Activate API.

herosms-api

通过无第三方依赖的 CLI 使用 HeroSMS。默认走官方 SMS-Activate 兼容端点完成激活生命周期，并用 REST v1 查询 activation offers。

入口

$py = "D:\reverse_ENV\.venv\Scripts\python.exe"
$cli = "D:\reverse_ENV\skill\herosms-api\scripts\herosms.py"

所有业务结果输出 JSON。--pretty 必须放在命令组之前，例如：

& $py $cli --pretty account balance

配置凭据

真实凭据统一使用 Windows 用户环境变量 HEROSMS_API_KEY。新启动的 Codex、Claude 和终端会直接继承；CLI 还会只读 HKCU\Environment，因此当前已启动会话也能立即使用。先检查，不输出 key：

& $py $cli --pretty config show

凭据优先级：

1. 当前进程 HEROSMS_API_KEY
2. Windows 用户环境变量 HEROSMS_API_KEY
3. %USERPROFILE%\.herosms\credentials.json 兼容回退

只有环境变量无法使用时，才交互式写入兼容凭据文件：

& $py $cli config set

禁止把 key 放进命令参数、仓库文件、.codex/config.toml、.claude/settings*.json、skill 文件、日志或回复正文。

标准流程

1. 验证账户

& $py $cli --pretty health
& $py $cli --pretty account balance

2. 查服务、国家、价格和库存

不要凭记忆写 service/country ID，先查目录：

& $py $cli --pretty catalog countries
& $py $cli --pretty catalog services --country 6
& $py $cli --pretty catalog prices --service tg --country 6
& $py $cli --pretty catalog offers --services tg --countries 6

catalog offers 使用 REST v1；其他目录命令使用 SMS-Activate 兼容 API。两路结果冲突时，以购买前最新一次 catalog prices/offers 和 getNumberV2 返回为准。

3. 购买号码

购买会扣费，必须同时给出价格上限和显式确认：

& $py $cli --pretty activation buy `
  --service tg `
  --country 6 `
  --max-price 0.30 `
  --yes

默认调用 getNumberV2。仅在旧集成明确需要文本响应时加 --v1。不要在用户没有确认 service、country、max-price 时代买号码。

4. 接收验证码

目标站点接受号码并触发短信后，将 activation 标记为 ready，再轮询：

& $py $cli --pretty activation ready --id 123456 --yes
& $py $cli --pretty activation poll --id 123456 --poll-timeout 120 --interval 5

只查一次状态：

& $py $cli --pretty activation status --id 123456
& $py $cli --pretty activation status --id 123456 --v2

读取该 activation 的全部短信：

& $py $cli --pretty activation sms --id 123456

5. 收尾

收到并确认验证码后完成 activation：

& $py $cli --pretty activation complete --id 123456 --yes

不再使用且符合平台取消条件时取消：

& $py $cli --pretty activation cancel --id 123456 --yes

需要重发时：

& $py $cli --pretty activation resend --id 123456 --yes

CLI 不会在 poll 超时后自动 complete 或 cancel，避免错误结算。

查询已有记录

& $py $cli --pretty activation active --limit 20
& $py $cli --pretty activation history --size 20

执行约束

• 购买前先查价格/库存，并始终设置可接受的 --max-price。
• buy/ready/resend/complete/cancel/config clear 都要求 --yes，不得绕过。
• 轮询默认 5 秒一次；不要为了抢码把间隔压到 1 秒以下。官方账户限额为 40 RPS，超限可能短暂封禁。
• BAD_KEY、NO_NUMBERS、NO_BALANCE、WRONG_MAX_PRICE 等会输出结构化错误并返回非零 exit code。
• Codex 用户入口为 %USERPROFILE%\.codex\skills\herosms-api\SKILL.md，Claude 用户入口为 %USERPROFILE%\.claude\skills\herosms-api\SKILL.md；两者只路由到本项目 source skill，不复制脚本或凭据。
• 真实 health 未通过时，只能运行本地测试和认证门禁，不能声称购买、收码或退款已实测。
• 需要接口、状态码、现成库对比或证据来源时，读取 references/api.md。

验证

& $py -m unittest discover `
  -s "D:\reverse_ENV\skill\herosms-api\tests" `
  -p "test_*.py" `
  -v