Stripe Link Cli

Платежи агента через Stripe Link — карты, SPT, подтверждения.

Метаданные навыка

Справочник: полный SKILL.md

Навык Stripe Link CLI

Оборачивает @stripe/link-cli, чтобы Hermes мог совершать покупки от имени пользователя с помощью одноразовых виртуальных карт или общих платёжных токенов (SPT). Каждая трата проходит через подтверждение в приложении Link (мобильном или веб) — сам себе Hermes покупку одобрить не может.

Пока что работает только в США (требование аккаунта Link). Windows исходный CLI не поддерживает, поэтому навык ограничен платформами [linux, macos].

Когда использовать

Фразы-триггеры:

• «купи X», «оплати X», «сделай покупку», «оформи заказ»
• «получи мне карту», «нужен способ оплаты»
• «войди в Link», «подключи мой кошелёк Link»
• ответ HTTP 402 от API продавца с www-authenticate: ... method="stripe"

Если пользователю нужен платный вызов API (HTTP 402, без формы оформления заказа), путь card не подходит — используйте SPT через этот же навык либо передайте задачу навыку mpp-agent.

Требования

• Node.js 20+ в PATH (node --version)
• нахождение в США (требование аккаунта Link)

Аккаунт Link, способ оплаты и приложение для подтверждения трат не обязаны быть настроены до того, как Hermes попытается заплатить — CLI проведёт пользователя через них при первом запуске:

• аккаунт Link на https://app.link.com — создаётся или привязывается во время первой авторизации link-cli
• хотя бы один способ оплаты — добавляется при первом запуске на https://app.link.com/wallet
• приложение Link (мобильное или веб) — открывается, чтобы подтвердить первый запрос на трату в момент его создания

Переменные окружения не нужны — состояние авторизации CLI хранит локально, в собственном каталоге конфигурации.

Установка

Поставьте один раз, глобально:

npm install -g @stripe/link-cli

Либо вызывайте на лету через npx @stripe/link-cli. В навыке ниже используется форма с установленным link-cli.

Как запускать

Все команды выполняются через инструмент terminal. CLI сам определяет вызов без TTY и по умолчанию выдаёт компактный вывод toon — для модели это нормально. Передайте --format json, если шагу нужны структурированные поля.

Узнать список команд: link-cli --llms-full. Получить схему команды перед вызовом: link-cli <command> --schema.

Порядок действий

1. Проверьте или установите авторизацию

link-cli auth status

Если авторизации нет, войдите с понятным именем клиента (эта подпись отображается в приложении Link у пользователя):

link-cli auth login --client-name "Hermes" --interval 5 --timeout 300

Форма --interval/--timeout опрашивает статус прямо в процессе, поэтому агенту не нужно вручную обрабатывать шаг _next. Выведите пользователю URL для подтверждения и фразу, затем дождитесь, пока CLI вернёт управление.

Не переходите дальше этого шага, пока auth status не подтвердит вход.

2. Оцените продавца перед созданием запроса на трату

Определите тип учётных данных:

Для ответов 402 не разбирайте challenge вручную. Передайте заголовок как есть:

link-cli mpp decode --challenge '<full WWW-Authenticate header>'

Так challenge проверяется, а из него извлекаются ID сети и расшифрованное тело запроса.

3. Получите список способов оплаты и адресов доставки

link-cli payment-methods list
link-cli shipping-address list

Берите первую запись, если пользователь не указал иначе. Поле id из payment-methods list — это --payment-method-id на следующем шаге.

4. Создайте запрос на трату

Подтвердите итоговую сумму с пользователем, прежде чем выполнять эту команду. Суммы указываются в центах.

link-cli spend-request create \
  --payment-method-id <pm_id> \
  --merchant-name "<name>" \
  --merchant-url "<url>" \
  --context "<one sentence: what is being purchased and why>" \
  --amount <cents> \
  --line-item "name:<item>,unit_amount:<cents>,quantity:1" \
  --total "type:total,display_text:Total,amount:<cents>" \
  --request-approval

Для продавцов MPP добавьте --credential-type shared_payment_token.

--request-approval шлёт пуш в приложение Link и опрашивает статус, пока пользователь не подтвердит или не отклонит запрос. При отклонении или таймауте CLI завершается с ненулевым кодом.

5. Получите учётные данные — БЕЗОПАСНО

Не выводите данные карты в stdout. Используйте --output-file, чтобы номер карты (PAN) не попал в транскрипт или логи агента:

link-cli spend-request retrieve <lsrq_id> \
  --include card \
  --output-file ~/.hermes/cache/scratch/link-card.json \
  --format json

Файл создаётся с правами 0600; в stdout попадают только замаскированные поля (бренд, последние 4 цифры, срок действия) и путь card_output_file.

6. Используйте учётные данные

• Для веб-оформления: передайте путь к файлу пользователю ЛИБО инструменту управления браузером, который заполнит форму прямо с диска. Никогда не загружайте файл карты в контекст рассуждений агента через read_file или cat.

• Для продавцов MPP:

  link-cli mpp pay <merchant-url> \
    --spend-request-id <lsrq_id> \
    --method POST \
    --data '<json body>'

7. Уберите за собой

Удалите файл карты сразу, как только покупка завершена:

rm -f ~/.hermes/cache/scratch/link-card.json

Опционально: запуск как MCP-сервер

@stripe/link-cli --mcp отдаёт те же команды в виде MCP-инструментов через stdio. Чтобы зарегистрировать его в нативном MCP Hermes:

hermes mcp add stripe-link --command "npx" --args "@stripe/link-cli --mcp"

После этого hermes mcp list должен показать stripe-link. Правила подтверждения те же — MCP не обходит шаг подтверждения в приложении Link.

Подводные камни

• Только США. За пределами США auth login завершится ошибкой. Сообщите об этом пользователю и не повторяйте попытки.
• Номер карты (PAN) не должен попадать в контекст агента. Используйте --output-file каждый раз. Если вы уже получили данные без него, одного link-cli auth logout мало — карта одноразовая, но правило немедленного удаления действует в любом случае.
• --request-approval блокирует выполнение, пока пользователь не отреагирует. Если пользователь недоступен, CLI дойдёт до таймаута. Сообщите об этом до запуска команды.
• Многошаговые команды _next. Некоторые команды возвращают _next.command, который нужно выполнить для продолжения. В сомнительных случаях предпочитайте флаги опроса в процессе (--interval/--timeout).
• Формат вывода по умолчанию — toon в режиме без TTY. Для прозы годится, но если дальнейшему шагу нужно разобрать конкретное поле, передайте --format json.
• Не выбирайте card по умолчанию. Шаг с оценкой продавца (раздел 2) существует потому, что неверный тип учётных данных либо молча проваливает покупку, либо раскрывает больше данных, чем нужно.

Проверка

link-cli --version && link-cli auth status

Код выхода 0 означает, что установлено и вход выполнен.