Перейти к основному содержимому

Stripe Link Cli

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

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

ИсточникОпционально — установка через vibeos skills install official/payments/stripe-link-cli
Путьoptional-skills/payments/stripe-link-cli
Версия0.1.0
АвторTeknium (teknium1), VibeOS
ЛицензияMIT
Платформыlinux, macos
ТегиPayments, Stripe, Link, Checkout, MPP
Связанные навыкиmpp-agent, stripe-projects

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

к сведению

Ниже приведено полное определение навыка, которое VibeOS загружает при его активации. Это инструкции, которые видит агент, когда навык активен.

Навык Stripe Link CLI

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

На данный момент только для США (требуется учётная запись Link). Windows не поддерживается upstream 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, способ оплаты и приложение для одобрения трат НЕ обязательно настраивать до того, как VibeOS попытается оплатить — CLI проведёт пользователя через них при первом запуске:

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

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

Установка​

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

npm install -g @stripe/link-cli

Или вызывайте ad-hoc через npx @stripe/link-cli. Навык ниже использует форму установленного link-cli.

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

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

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

Процедура​

1. Проверка / установка аутентификации​

link-cli auth status

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

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

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

Не переходите к следующему шагу, пока auth status не подтвердит вход.

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

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

Поверхность мерчанта--credential-type
Стандартная веб-форма оформления заказа / Stripe Elementscard (по умолчанию)
Возвращает HTTP 402 с method="stripe" в www-authenticateshared_payment_token
Возвращает HTTP 402 без method="stripe"не поддерживается — остановитесь

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

link-cli mpp decode --challenge '<полный заголовок WWW-Authenticate>'

Это проверяет 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 "<имя>" \
  --merchant-url "<url>" \
  --context "<одно предложение: что покупается и зачем>" \
  --amount <центы> \
  --line-item "name:<товар>,unit_amount:<центы>,quantity:1" \
  --total "type:total,display_text:Итого,amount:<центы>" \
  --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 /tmp/link-card.json \
  --format json

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

6. Использование учётных данных​

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

  • Для мерчантов MPP:

    link-cli mpp pay <url-мерчанта> \
      --spend-request-id <lsrq_id> \
      --method POST \
      --data '<json тело>'

7. Очистка​

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

rm -f /tmp/link-card.json

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

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

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

Затем vibeos 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 означает, что установка выполнена и выполнен вход.