@statuser/cli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Statuser
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,449 @@
-# Temporary Holding Version
+# CLI Statuser
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/@statuser/cli.svg)](https://www.npmjs.com/package/@statuser/cli)
+[![CI](https://github.com/statuser-cloud/cli/actions/workflows/ci.yml/badge.svg)](https://github.com/statuser-cloud/cli/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Утилита командной строки для [Statuser](https://statuser.cloud). Добавляет и настраивает серверы, описывает серверы и сценарные проверки как код, ставит проверки на паузу на время деплоя, ведёт плановые работы и отчёты на странице статуса, отправляет heartbeat из крон-задач. Работает поверх [публичного API Statuser](https://statuser.cloud/api-reference) с авторизацией по API-ключу.
+
+```console
+$ statuser scenarios test checks/checkout.spec.ts
+Прогоняю сценарий…
+Сценарий не прошёл.
+Тест: оформление заказа
+Ошибка: expect(locator).toBeVisible() failed
+Locator: getByRole('heading', { name: 'Мои заказы' })
+Скриншот: https://…/screenshot.png
+Видео: https://…/video.webm
+Трейс: https://…/trace.zip
+```
+
+## Содержание
+
+- [Установка](#установка)
+- [Быстрый старт](#быстрый-старт)
+- [Серверы](#серверы)
+- [Серверы как код](#серверы-как-код)
+- [Сценарии](#сценарии)
+- [Деплой и плановые работы](#деплой-и-плановые-работы)
+- [Heartbeat](#heartbeat)
+- [Инциденты](#инциденты)
+- [Отчёты на странице статуса](#отчёты-на-странице-статуса)
+- [Готовые файлы CI](#готовые-файлы-ci)
+- [Справка](#справка)
+
+## Установка
+
+Через npm, если на машине есть Node.js 20.19 или новее:
+
+```bash
+npm install -g @statuser/cli
+```
+
+Пакет называется `@statuser/cli`, команда после установки — `statuser`.
+
+В CI устанавливать не обязательно, достаточно `npx`:
+
+```bash
+npx -y @statuser/cli scenarios deploy
+```
+
+Без Node — один исполняемый файл со страницы [релизов](https://github.com/statuser-cloud/cli/releases/latest):
+
+```bash
+curl -fsSL https://github.com/statuser-cloud/cli/releases/latest/download/statuser-linux-x64.tar.gz | tar -xz
+sudo mv statuser /usr/local/bin/
+```
+
+Для других систем замените `linux-x64` на `linux-arm64`, `macos-arm64` или `macos-x64`. Для Windows скачайте `statuser-windows-x64.zip`. Контрольные суммы лежат в файле `SHA256SUMS` того же релиза. Если на macOS файл скачан браузером, система не даст его запустить, пока не снять отметку: `xattr -d com.apple.quarantine statuser`.
+
+Справка и сообщения выводятся на языке системы: на русском, если `LANG` начинается с `ru`, иначе на английском. Справка по любой команде: `statuser <команда> --help`.
+
+## Быстрый старт
+
+1. Создайте ключ в [панели Statuser](https://statuser.cloud/my/account/api-keys): «Настройки аккаунта → API и MCP».
+2. Сохраните его на этой машине:
+
+   ```console
+   $ statuser login
+   API-ключ (панель Statuser → Настройки аккаунта → API и MCP):
+   Готово: you@example.com. Ключ сохранён в /home/you/.config/statuser/config.json
+   ```
+
+3. Посмотрите серверы аккаунта:
+
+   ```console
+   $ statuser servers list
+   ID    Имя                Протокол  Статус  Хост                     Проект
+   1874  Сайт магазина      http      online  https://shop.example.com 100000
+   2041  Вход в кабинет     scenario  online  scenario://2041          100000
+   ```
+
+Файл с ключом доступен только владельцу. В CI передавайте ключ переменной `STATUSER_API_KEY`, а не флагом: аргументы команды видны в истории и в списке процессов.
+
+## Серверы
+
+```bash
+statuser servers add https://shop.example.com --name "Магазин" --project 100000
+statuser servers add 203.0.113.10 --name "Шлюз"
+statuser servers add db.example.com --protocol tcp --port 5432
+statuser servers add --protocol heartbeat --name "Бэкап" --interval 86400
+
+statuser servers list --project 100000 --protocol http
+statuser servers get 101
+statuser servers checks 101 --since 7d
+statuser servers test-notify 101
+statuser servers update 101 --name "Магазин (прод)" --host https://shop.example.ru
+statuser servers delete 101
+```
+
+Протокол определяется по адресу: для URL это HTTP-проверка, для IP — ping. У домена без схемы укажите `--protocol`. Остальные настройки получают значения по умолчанию, как в панели. Если API откажет в создании, CLI скажет об этом до записи. Без `--project` сервер попадает в самый старый проект аккаунта.
+
+- `checks` показывает проверки за период, по умолчанию за сутки: статус и задержку в каждой локации.
+- `test-notify` отправляет тестовый алёрт в те же каналы, куда ушёл бы настоящий.
+- `update` с `--name`, `--host` или `--description` меняет один сервер.
+- `delete` удаляет сервер вместе с историей проверок и инцидентами, поэтому сначала спрашивает подтверждение. В CI спросить некого, там нужен `--yes`.
+
+### Массовые правки
+
+```bash
+statuser servers update --project 100000 --interval 60 --regions msk-1,spb-1 --dry-run
+statuser servers update --project 100000 --protocol http --ssl --domain
+statuser servers update 101 102 --latency-alert 800
+```
+
+Флаги: `--interval`, `--timeout`, `--regions`, `--confirm-delay`, `--ssl` / `--no-ssl`, `--domain` / `--no-domain`, `--blocklist` / `--no-blocklist`, `--latency-alert <мс>` / `--no-latency-alert`. Отправляются только поля, которые действительно меняются. Если флаг не относится к протоколу сервера, например `--ssl` у ping, сервер пропускается с объяснением. Ошибка на одном сервере не останавливает остальные, `--json` возвращает `done`, `skipped` и `failed`.
+
+## Серверы как код
+
+Серверы проекта описываются в файле `statuser.json`, в секции `servers`: HTTP, keyword, ping, TCP, DNS, heartbeat и LLM.
+
+```bash
+statuser export --project 100000 -o statuser.json   # выгрузить, что есть сейчас
+statuser diff                                       # что изменит apply
+statuser apply                                      # привести проект к файлу
+```
+
+```json
+{
+  "project_id": 100000,
+  "servers": [
+    {
+      "id": 1874,
+      "name": "Сайт магазина",
+      "protocol": "http",
+      "host": "https://shop.example.com",
+      "check_interval": 60,
+      "locations": ["msk-1", "spb-1"],
+      "is_ssl_check": true,
+      "headers": [{ "key": "Authorization", "value": "$SHOP_API_TOKEN" }]
+    },
+    { "name": "Бэкап базы", "protocol": "heartbeat", "check_interval": 86400 }
+  ],
+  "scenarios": []
+}
+```
+
+- Поля называются так же, как в [API](https://statuser.cloud/api-reference). Сервер узнаётся по `id`, а без него — по имени внутри проекта.
+- Секреты API не возвращает, поэтому в файле они задаются ссылкой на переменную окружения: `"http_auth_password": "$SHOP_PASSWORD"`. Значения секретных заголовков `export` заменяет такими же ссылками и называет переменные. Строку, которая сама начинается с `$`, пишите как `$$…`. Адрес, тело запроса и логин выгружаются как есть, поэтому проверьте файл перед коммитом.
+- Ошибки в файле `apply` показывает до первой записи. Если запись всё же остановилась на ошибке, повторный `apply` продолжит с этого места.
+- `apply` не удаляет серверы и не меняет их протокол. Серверы, которых нет в файле, только показываются в плане.
+
+## Сценарии
+
+Сценарий — это Playwright-тест, который Statuser прогоняет по расписанию в настоящем браузере: вход в кабинет, корзина, цепочка запросов к API. С CLI тесты лежат в вашем репозитории рядом с кодом сайта и выкатываются вместе с ним.
+
+### Тест
+
+`checks/checkout.spec.ts`:
+
+```ts
+import { test, expect } from '@playwright/test';
+
+test('оформление заказа', async ({ page }) => {
+  await page.goto('https://shop.example.com/login');
+  await page.getByLabel('Email').fill(process.env.SHOP_LOGIN!);
+  await page.getByLabel('Пароль').fill(process.env.SHOP_PASSWORD!);
+  await page.getByRole('button', { name: 'Войти' }).click();
+  await expect(page.getByRole('heading', { name: 'Мои заказы' })).toBeVisible();
+});
+```
+
+Один файл до 64 КБ. Из пакетов доступен `@playwright/test`, свои вспомогательные файлы подключить нельзя. Логины и пароли передаются только через `process.env`.
+
+### Прогнать до выкладки
+
+```bash
+statuser scenarios test checks/checkout.spec.ts \
+  --location msk-1 --env SHOP_LOGIN='$SHOP_LOGIN' --env SHOP_PASSWORD='$SHOP_PASSWORD'
+```
+
+Сервер при этом не создаётся, история проверок и инциденты не меняются. Значение вида `$NAME` берётся из окружения, поэтому пароль не попадает в историю команд. Ссылки на скриншот, видео и трейс действуют час.
+
+### Выкатить
+
+`statuser.json` в корне репозитория:
+
+```json
+{
+  "project_id": 100000,
+  "scenarios": [
+    {
+      "name": "Оформление заказа",
+      "file": "checks/checkout.spec.ts",
+      "interval": 300,
+      "timeout": 60,
+      "location": "msk-1",
+      "env": { "SHOP_LOGIN": "$SHOP_LOGIN", "SHOP_PASSWORD": "$SHOP_PASSWORD" }
+    }
+  ]
+}
+```
+
+```console
+$ statuser scenarios deploy --dry-run
+План для проекта #100000:
+  + создать «Оформление заказа»
+  ~ изменить «Вход в кабинет» (#2041): interval
+Это план (--dry-run), ничего не изменено.
+
+$ statuser scenarios deploy
+```
+
+| Поле         | Что значит                                                                                       |
+| ------------ | ------------------------------------------------------------------------------------------------ |
+| `project_id` | Проект, в котором живут сценарии. Id показывает `statuser projects list`                         |
+| `name`       | Имя сервера в Statuser. По нему сценарий узнаётся внутри проекта                                 |
+| `id`         | Необязательно. Нужен, чтобы переименовать сценарий: без него новое имя заведёт новый сервер      |
+| `file`       | Путь к тесту относительно `statuser.json`                                                        |
+| `interval`   | Как часто проверять, секунд: от 60 до 86 400 и не меньше таймаута. По умолчанию 300              |
+| `timeout`    | Сколько ждать прогон, секунд: 15, 30, 45, 60 или 120. По умолчанию 30                            |
+| `location`   | Откуда проверять: `msk-1`, `spb-1`, `ala-1`, `nyc-1` или `ams-1`. По умолчанию `msk-1`           |
+| `env`        | Переменные окружения теста. Имена — заглавными буквами, значение `$NAME` берётся из окружения CI |
+
+- Весь файл проверяется до первой записи: ошибка в пятом сценарии не оставит первые четыре выкаченными.
+- `env` задаёт полный набор переменных: имя, которое убрали из файла, удаляется и на сервере. Если поля `env` нет, переменные на сервере остаются как есть.
+- Сценарии проекта, которых нет в файле, не удаляются, а только показываются в плане.
+- Число сценариев, минимальный интервал и максимальный таймаут зависят от тарифа.
+
+### Проверить после выкладки
+
+```bash
+statuser scenarios run 2041
+```
+
+Сохранённый сценарий прогоняется сразу, с теми же последствиями, что по расписанию: результат попадает в историю, а сбой открывает инцидент. Значения переменных сценария API не возвращает. CLI скрывает в выводе те из них, что лежат в окружении под теми же именами, и предупреждает об остальных.
+
+Код выхода у `scenarios test` и `scenarios run`: 0 — сценарий прошёл, 4 — не прошёл, 1 — сбой песочницы или API.
+
+## Деплой и плановые работы
+
+Пауза проверок избавляет команду от ложных алёртов на время деплоя, а плановые работы предупреждают клиентов о простое, который они заметят.
+
+### Пауза проверок на время деплоя
+
+Если сервис во время деплоя отвечает с ошибками, проверки поднимут команду ложными алёртами. Их можно поставить на паузу и вернуть после:
+
+```bash
+statuser servers pause --project 100000 --json > paused.json
+
+# … деплой …
+
+statuser servers resume --from paused.json
+```
+
+`resume --from` возобновляет только то, что поставил на паузу шаг `pause`: серверы, которые уже стояли на паузе, такими и останутся.
+
+### Плановые работы на странице статуса
+
+Когда простой заметят клиенты, например при переезде базы или обновлении на полчаса, их предупреждают плановыми работами: окно появляется на странице статуса, подписчики получают письмо. Для короткого деплоя это лишнее, иначе рассылка уходила бы на каждый релиз.
+
+Объявить заранее:
+
+```bash
+statuser maintenance schedule --page 12 --all-servers --at 2026-11-20T03:00+03:00 --for 1h \
+  --title "Переезд базы данных" --description "Магазин будет недоступен до 30 минут"
+statuser maintenance list --page 12
+statuser maintenance delete 77 --page 12
+```
+
+Открыть и закрыть, когда работы идут сейчас:
+
+```bash
+statuser maintenance start --page 12 --all-servers \
+  --title "Переезд базы данных" --description "Магазин будет недоступен до 30 минут" \
+  --for 30m --json > maintenance.json
+
+# … работы …
+
+statuser maintenance end --page 12 "$(jq .id maintenance.json)" --message "Работы завершены"
+```
+
+- `--servers 101,102` выбирает серверы страницы статуса, `--all-servers` берёт все. `--for` задаёт длительность окна: `30m`, `2h`, `1h30m`. `--at` задаёт начало в будущем.
+- `maintenance end` без `--message` только переносит время окончания. С `--message` в таймлайне работ появляется запись, и подписчики получают уведомление. Повторный `end` дату не сдвигает и то же сообщение второй раз не публикует, поэтому шаг можно безопасно перезапустить.
+- Плановые работы алёрты не глушат. Если проверки на это время не нужны, добавьте паузу.
+
+## Heartbeat
+
+```bash
+STATUSER_HEARTBEAT_TOKEN=… statuser run -- ./backup.sh
+```
+
+Если команда завершилась с кодом 0, Statuser получает сигнал «работает», с другим кодом — «ошибка», и инцидент открывается сразу. Код выхода `run` — код самой команды: если сигнал не дошёл из-за сети, успешный бэкап не превратится в упавший. Если команду убил сигнал, код равен 128 + номер сигнала, как в shell.
+
+Строка для crontab:
+
+```cron
+0 3 * * * STATUSER_HEARTBEAT_TOKEN=… /usr/local/bin/statuser run -- /opt/scripts/backup.sh
+```
+
+У крона короткий `PATH`, поэтому путь к `statuser` указан полностью. Его покажет `which statuser`.
+
+- Токен — последняя часть адреса heartbeat-сервера: `https://hb.statuser.cloud/<токен>`. API-ключ на машине с кроном не нужен. Передавайте токен переменной, а не флагом `--heartbeat`: аргументы видны в списке процессов, пока идёт команда.
+- Если на машине есть API-ключ, токен можно не копировать: `statuser run --server 101 -- ./backup.sh`.
+- Пока не пришёл первый сигнал, Statuser не знает, что задача запущена, и пропуски не считает. Интервал и допустимую задержку heartbeat-сервера задайте с запасом на самую долгую задачу.
+- Разовый сигнал без команды: `statuser heartbeat ping "$TOKEN"`, сигнал ошибки — с `--fail`.
+
+## Инциденты
+
+```bash
+statuser incidents list --open
+statuser incidents list --since 7d --project 100000
+statuser incidents get 5021
+statuser incidents ai 5021                      # разбор Statuser AI
+statuser incidents pdf 5021 -o incident-5021.pdf
+statuser incidents comment 5021 -m "Выкатили исправление"
+statuser incidents delete 5021
+```
+
+`--since` и `--until` фильтруют по времени начала инцидента: `24h`, `7d` или дата. Диагностика и разбор Statuser AI есть на платных тарифах. Если данных для разбора нет, он так и скажет. PDF сохраняется с доступом только для владельца, существующий файл перезаписывается только с `--force`. `delete` спрашивает подтверждение, как и удаление серверов.
+
+## Отчёты на странице статуса
+
+Публичные отчёты об инцидентах видят посетители страницы статуса, а подписчики получают их письмом.
+
+```bash
+statuser reports create --page 12 --all-servers --status degraded \
+  --title "Медленная оплата" --message "Разбираемся с задержками платежей"
+statuser reports update 88 --page 12 --message "Нашли причину, выкатываем исправление"
+statuser reports resolve 88 --page 12 --message "Платежи проходят штатно"
+statuser reports list --page 12
+```
+
+Сообщение обязательно в каждой команде: оно уходит подписчикам на языке страницы, поэтому CLI своих текстов не подставляет. `resolve` уже закрытого отчёта ничего не отправляет, так что шаг CI можно безопасно перезапустить.
+
+## Готовые файлы CI
+
+Примеры можно скопировать в репозиторий как есть, поменяв id проекта и имена переменных.
+
+### GitHub Actions
+
+Прогнать тесты и выкатить сценарии при изменении тестов:
+
+```yaml
+name: Сценарии Statuser
+on:
+  push:
+    branches: [main]
+    paths: ['checks/**', 'statuser.json']
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    env:
+      STATUSER_API_KEY: ${{ secrets.STATUSER_API_KEY }}
+      SHOP_LOGIN: ${{ secrets.SHOP_LOGIN }}
+      SHOP_PASSWORD: ${{ secrets.SHOP_PASSWORD }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - name: Прогнать тесты
+        run: |
+          for file in checks/*.spec.ts; do
+            npx -y @statuser/cli scenarios test "$file" \
+              --env SHOP_LOGIN='$SHOP_LOGIN' --env SHOP_PASSWORD='$SHOP_PASSWORD'
+          done
+      - name: Выкатить
+        run: npx -y @statuser/cli scenarios deploy
+```
+
+### GitLab CI
+
+Пауза проверок вокруг деплоя. `after_script` выполняется и при упавшем деплое, поэтому проверки возобновятся в любом случае:
+
+```yaml
+deploy:
+  image: node:22
+  variables:
+    STATUSER_PROJECT: '100000'
+  before_script:
+    - npx -y @statuser/cli servers pause --project "$STATUSER_PROJECT" --json > paused.json
+  script:
+    - ./deploy.sh
+  after_script:
+    - npx -y @statuser/cli servers resume --from paused.json
+```
+
+`STATUSER_API_KEY` задайте в настройках CI/CD проекта как замаскированную переменную.
+
+## Справка
+
+Команды, которые нужны реже, и общие правила: переменные окружения, коды выхода, работа с ключом и повтор запросов.
+
+### Остальные команды
+
+```bash
+statuser projects list
+statuser pages list
+statuser api /v1/servers/101 -X PATCH -F check_interval=120
+statuser whoami
+statuser logout
+```
+
+`projects list` и `pages list` показывают id для `--project` и `--page`.
+
+`statuser api` отправляет запрос к любому методу [API](https://statuser.cloud/api-reference), как `gh api`. Поля из `-F` для GET и DELETE уходят в query, для остальных методов — в тело запроса. `-F` разбирает значение как JSON (`-F on=true` передаёт логическое значение), `-f` всегда передаёт строку. Тело целиком: `--input file.json` или `--input -` из stdin.
+
+С флагом `--json` любая команда печатает машиночитаемый ответ в stdout, а сообщения о ходе работы уходят в stderr. `--debug` печатает запросы, ключ и токены при этом скрыты.
+
+### Переменные окружения
+
+| Переменная                 | Что задаёт                                             |
+| -------------------------- | ------------------------------------------------------ |
+| `STATUSER_API_KEY`         | API-ключ. Главнее ключа, сохранённого `statuser login` |
+| `STATUSER_HEARTBEAT_TOKEN` | Токен heartbeat для `statuser run` и `heartbeat ping`  |
+| `STATUSER_API_URL`         | Адрес API, по умолчанию `https://api.statuser.cloud`   |
+| `LANG`, `LC_ALL`           | Язык сообщений: `ru…` — русский, иначе английский      |
+
+### Коды выхода
+
+| Код | Когда                                                  |
+| --- | ------------------------------------------------------ |
+| 0   | Успех                                                  |
+| 1   | Ошибка API или сети, сбой песочницы сценариев          |
+| 2   | Неверные аргументы или файл конфигурации               |
+| 3   | Нет ключа или ключ не принят                           |
+| 4   | Сценарий не прошёл (`scenarios test`, `scenarios run`) |
+
+### Как это устроено
+
+- **Сценарии выполняются не на вашей машине**, а в изолированной песочнице Statuser, из выбранного города, так же, как прогон по расписанию. Поэтому `scenarios test` показывает то, что увидит мониторинг, а не то, что видно из офиса.
+- **Ключ уходит только на адрес API.** CLI не идёт за редиректами и не отправляет ключ на другой адрес. Ключ, сохранённый для одного адреса API, не используется для другого.
+- **CLI ничего не удаляет сам.** `apply` и `deploy` только перечисляют серверы, которых нет в файле. Удаляют явные команды `delete`, и только после подтверждения.
+- **Запрос повторяется, только когда он точно не ушёл**: если соединение не установилось, CLI делает две повторные попытки, после ответа 429 — ждёт паузу из `Retry-After`. Если запись ушла, но ответа нет (обрыв, таймаут, 5xx), `apply` и `deploy` останавливаются и сообщают, что исход неизвестен. Перед повтором запустите `statuser diff`.
+
+## Смотрите также
+
+[MCP-сервер Statuser](https://github.com/statuser-cloud/mcp) даёт то же API ИИ-клиентам: Claude Code, Cursor, VS Code.
+
+## Обратная связь
+
+Ошибки и предложения — в [issues](https://github.com/statuser-cloud/cli/issues). Об уязвимостях сообщайте приватно — см. [SECURITY.md](SECURITY.md).
+
+Общие вопросы по API — в [документации Statuser](https://statuser.cloud/api-reference) или на [info@statuser.cloud](mailto:info@statuser.cloud).
+
+## Лицензия
+
+MIT — см. [LICENSE](LICENSE).

package/dist/client.js

@@ -0,0 +1,163 @@
+import { createRequire } from 'node:module';
+import { CliError, ExitCode, NotSentError, parseApiErrorBody, } from './errors.js';
+import { t } from './i18n.js';
+export const CLI_VERSION = typeof __STATUSER_VERSION__ === 'string'
+    ? __STATUSER_VERSION__
+    : createRequire(import.meta.url)('../package.json').version;
+const USER_AGENT = `statuser-cli/${CLI_VERSION}`;
+const MAX_429_RETRIES = 2;
+const MAX_429_WAIT_SECONDS = 30;
+const DEFAULT_TIMEOUT_MS = 60_000;
+const MAX_CONNECT_RETRIES = 2;
+const CONNECT_RETRY_DELAY_MS = 1_000;
+// The connection was never set up, so the request did not leave: repeating
+// it cannot apply a write twice. A reset or timeout after the request went
+// out is not here — the API may already have acted on it.
+const NOT_SENT_CODES = new Set([
+    'ECONNREFUSED',
+    'EHOSTUNREACH',
+    'ENETUNREACH',
+    'EAI_AGAIN',
+    'UND_ERR_CONNECT_TIMEOUT',
+]);
+export class StatuserClient {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async call(opts) {
+        return (await this.execute(opts, false));
+    }
+    /** For files (PDF reports): the body is returned as bytes, never parsed. */
+    async callBinary(opts) {
+        return (await this.execute(opts, true));
+    }
+    async execute(opts, binary) {
+        const url = this.buildUrl(opts.path, opts.query);
+        const headers = {
+            'user-agent': USER_AGENT,
+            accept: binary ? '*/*' : 'application/json',
+        };
+        if (!opts.anonymous) {
+            if (!this.options.apiKey)
+                throw new CliError(t.noApiKey, ExitCode.Auth);
+            // A newline or space inside the key makes fetch throw an error that
+            // quotes the whole header — the key would land in stderr and CI logs.
+            if (!/^[\x21-\x7e]+$/.test(this.options.apiKey)) {
+                throw new CliError(t.apiKeyMalformed, ExitCode.Auth);
+            }
+            headers.authorization = `Bearer ${this.options.apiKey}`;
+        }
+        let body;
+        if (opts.body !== undefined) {
+            body = JSON.stringify(opts.body);
+            headers['content-type'] = 'application/json';
+        }
+        let connectRetries = 0;
+        let rateLimitRetries = 0;
+        for (;;) {
+            this.debug(`→ ${opts.method} ${redactUrl(url)}`);
+            let res;
+            try {
+                res = await fetch(url, {
+                    method: opts.method,
+                    headers,
+                    body,
+                    // Never follow redirects: the key must not travel to another origin.
+                    redirect: 'manual',
+                    signal: AbortSignal.timeout(opts.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+                });
+            }
+            catch (error) {
+                const reason = describeFetchError(error);
+                if (NOT_SENT_CODES.has(reason)) {
+                    if (connectRetries < MAX_CONNECT_RETRIES) {
+                        connectRetries += 1;
+                        this.debug(t.debugRetry(reason));
+                        await sleep(CONNECT_RETRY_DELAY_MS * connectRetries);
+                        continue;
+                    }
+                    throw new NotSentError(t.networkError(reason));
+                }
+                throw new CliError(t.networkError(reason));
+            }
+            this.debug(`← ${res.status}`);
+            if (res.status === 429 && rateLimitRetries < MAX_429_RETRIES) {
+                const wait = parseRetryAfter(res.headers.get('retry-after'));
+                if (wait !== null && wait <= MAX_429_WAIT_SECONDS) {
+                    rateLimitRetries += 1;
+                    await res.body?.cancel();
+                    await sleep(wait * 1000);
+                    continue;
+                }
+            }
+            if (binary && res.status >= 200 && res.status < 300) {
+                return {
+                    contentType: res.headers.get('content-type') ?? '',
+                    bytes: Buffer.from(await res.arrayBuffer()),
+                };
+            }
+            const text = await res.text();
+            if (res.status >= 200 && res.status < 300) {
+                if (!text)
+                    return null;
+                try {
+                    return JSON.parse(text);
+                }
+                catch {
+                    return text;
+                }
+            }
+            throw parseApiErrorBody(res.status, text);
+        }
+    }
+    buildUrl(path, query) {
+        if (!path.startsWith('/')) {
+            throw new CliError(t.apiPathInvalid, ExitCode.Usage);
+        }
+        const base = new URL(this.options.apiUrl);
+        const url = new URL(`${this.options.apiUrl}${path}`);
+        // `//evil.example` or encoded tricks in the path must not change the host.
+        if (url.origin !== base.origin) {
+            throw new CliError(t.foreignOrigin(url.toString()), ExitCode.Usage);
+        }
+        for (const [key, value] of Object.entries(query ?? {})) {
+            if (value !== undefined)
+                url.searchParams.append(key, String(value));
+        }
+        return url.toString();
+    }
+    debug(line) {
+        if (this.options.debug)
+            process.stderr.write(`${line}\n`);
+    }
+}
+/** Heartbeat tokens live in the path; they are credentials, so debug output hides them. */
+export function redactUrl(url) {
+    return url.replace(/(\/heartbeat\/)[^/?#]+/, '$1***');
+}
+function describeFetchError(error) {
+    if (error instanceof Error) {
+        if (error.name === 'TimeoutError')
+            return 'timeout';
+        const cause = error
+            .cause;
+        return cause?.code ?? cause?.message ?? error.message;
+    }
+    return String(error);
+}
+function parseRetryAfter(value) {
+    if (!value)
+        return null;
+    const seconds = Number(value);
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return seconds;
+    const date = Date.parse(value);
+    if (Number.isNaN(date))
+        return null;
+    return Math.max(0, Math.ceil((date - Date.now()) / 1000));
+}
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}