diff --git a/optional-skills/payments/mpp-agent/SKILL.md b/optional-skills/payments/mpp-agent/SKILL.md new file mode 100644 index 00000000000..f4817af047c --- /dev/null +++ b/optional-skills/payments/mpp-agent/SKILL.md @@ -0,0 +1,124 @@ +--- +name: mpp-agent +description: Pay HTTP 402 APIs via Machine Payments Protocol (MPP). +version: 0.1.0 +author: Teknium (teknium1), Hermes Agent +license: MIT +platforms: [linux, macos] +metadata: + hermes: + tags: [Payments, MPP, HTTP-402, Tempo, Stripe] + related_skills: [stripe-link-cli, stripe-projects] +--- + +# MPP Agent Skill + +Wraps the Machine Payments Protocol (MPP, https://mpp.dev) clients so Hermes can pay for per-request API access against servers that respond with `HTTP 402 Payment Required`. + +Three client options, all distributed via npm. Pick the lightest one that solves the user's need. Gated `[linux, macos]` while the broader payments tooling matures on Windows. + +## When to Use + +- A merchant API returns `HTTP 402` with a `www-authenticate` header — and the user wants to actually pay it, not just log the response. +- The user asks to "pay per request", "set up an agent wallet", "use Tempo / Privy / AgentCash", or wants to discover MPP-priced services. +- A Stripe Link spend has produced a Shared Payment Token (SPT) and the agent needs to attach it to the 402 challenge — in that flow, prefer `link-cli mpp pay` (see the `stripe-link-cli` skill). + +## Choosing a client + +| Tool | When | Setup | +|---|---|---| +| `link-cli` | User already has Stripe Link set up, or the 402 challenge advertises `method="stripe"` | see the `stripe-link-cli` skill | +| Tempo Wallet | MPP services with spend controls, service discovery | `tempo wallet login` | +| Privy Agent CLI | Multi-chain wallets, browser-based funding | `privy-agent-wallets login` | +| AgentCash | 300+ pre-priced APIs via one USDC.e balance | `npx agentcash onboard` | +| `mppx` | Dev + debugging, smallest dep surface | `npm install -g mppx` then `mppx account create` | + +Default: if the user already has Stripe Link configured or the 402 challenge specifies `method="stripe"`, use `link-cli mpp pay` (the `stripe-link-cli` skill). Otherwise `mppx` for one-off paid calls and debugging, and Tempo Wallet when the user wants persistent spend controls. + +## Prerequisites + +- Node.js 20+ on `PATH` +- A funded wallet (Tempo / Privy / AgentCash) OR an `mppx` account +- For Tempo / Privy / AgentCash: follow their respective onboarding skills: + - `https://tempo.xyz/SKILL.md` + - `https://agents.privy.io/skill.md` + - `https://agentcash.dev/skill.md` + +Use `web_extract` to fetch any of those SKILL.md files if the user picks one. + +## Procedure (mppx, fastest path) + +Run all commands through the `terminal` tool. + +### 1. Install + create an account + +``` +npm install -g mppx +mppx account create +``` + +Store the resulting account credentials wherever the CLI tells you (the CLI writes them under its own config — do not paste them into the agent transcript). + +### 2. Inspect the merchant's 402 challenge + +If the user gives you a URL, probe it first to confirm it actually speaks MPP: + +``` +curl -i +``` + +A real MPP 402 looks like: + +``` +HTTP/1.1 402 Payment Required +www-authenticate: tempo amount=0.1 currency=... +``` + +### 3. Pay the request + +``` +mppx +``` + +For non-GET methods or request bodies: + +``` +mppx --method POST --data '' +``` + +`mppx` handles the 402 challenge/credential dance automatically and prints the merchant's actual response on success. + +### 4. Verify the receipt + +`mppx` attaches the receipt header automatically. To inspect: + +``` +mppx -v +``` + +## Procedure (Tempo Wallet) + +The Tempo Wallet skill at https://tempo.xyz/SKILL.md is the canonical reference; fetch it with `web_extract` and follow it. Headline: + +``` +tempo wallet login +tempo wallet pay +``` + +Spend controls and service discovery live in the wallet UI at https://wallet.tempo.xyz. + +## Pitfalls + +- **`HTTP 402` without `method="stripe"` cannot be paid by Stripe Link.** If the challenge advertises only Tempo / other methods, use `mppx` (or whichever wallet matches) — Link will reject it. Conversely, if it advertises `method="stripe"`, prefer Link via the `stripe-link-cli` skill so the spend goes through the user's approved card. +- **Multiple challenges in one header.** `www-authenticate` may list several methods (e.g. `tempo, stripe`). The Link CLI's `mpp decode` will pick the Stripe one; `mppx` will pick Tempo. There's no single "right" client — pick by which wallet the user has funded. +- **Zero-amount challenges.** Some MPP endpoints charge `$0.00` and just want a proof credential. These work without a funded wallet. Don't refuse them as "broken." +- **Wallet keys never enter agent context.** All four clients store keys under their own config dirs (or generate per-session ephemeral keypairs, in Privy's case). Do not `cat`/`read_file` them. +- **Server-side MPP is a different skill.** If the user wants to ADD 402 to their own API, this skill is wrong — point them at https://mpp.dev/quickstart/server and the `mppx/nextjs` / `mppx/hono` / `mppx/express` / `mppx/elysia` middlewares. A dedicated `mpp-server` skill may land later. + +## Verification + +``` +mppx --version && mppx account list +``` + +Exit code 0 means installed and an account exists. diff --git a/optional-skills/payments/stripe-link-cli/SKILL.md b/optional-skills/payments/stripe-link-cli/SKILL.md new file mode 100644 index 00000000000..a2233829672 --- /dev/null +++ b/optional-skills/payments/stripe-link-cli/SKILL.md @@ -0,0 +1,184 @@ +--- +name: stripe-link-cli +description: Agent payments via Stripe Link — cards, SPT, approvals. +version: 0.1.0 +author: Teknium (teknium1), Hermes Agent +license: MIT +platforms: [linux, macos] +metadata: + hermes: + tags: [Payments, Stripe, Link, Checkout, MPP] + related_skills: [mpp-agent, stripe-projects] +--- + +# Stripe Link CLI Skill + +Wraps [@stripe/link-cli](https://github.com/stripe/link-cli) so Hermes can complete purchases on the user's behalf using one-time-use virtual cards or Shared Payment Tokens (SPT). Every spend is gated by an in-app approval in the Link mobile/web app — Hermes cannot self-approve. + +US-only at the moment (Link account requirement). Windows is not supported by the upstream CLI — this skill is gated `[linux, macos]`. + +## When to Use + +Trigger phrases: + +- "buy X", "pay for X", "make a purchase", "complete checkout" +- "get me a card", "I need a payment method" +- "log in to Link", "connect my Link wallet" +- HTTP 402 response from a merchant API with `www-authenticate: ... method="stripe"` + +If the user wants a paid API call (HTTP 402, no checkout form), the `card` path is wrong — use SPT via this same skill, or hand off to the `mpp-agent` skill. + +## Prerequisites + +- Node.js 20+ available on `PATH` (`node --version`) +- US-based (Link account requirement) + +The Link account, payment method, and spend-approval app do NOT need to be set up before Hermes attempts to pay — the CLI walks the user through them on first run: + +- A Link account at https://app.link.com — created/linked during first `link-cli` auth +- At least one payment method — added during first run at https://app.link.com/wallet +- The Link mobile/web app — opened to approve the first spend request when it's made + +No env vars required — auth state is stored locally by the CLI under its own config directory. + +## Install + +Install once, globally: + +``` +npm install -g @stripe/link-cli +``` + +Or invoke ad-hoc via `npx @stripe/link-cli`. The skill below uses the installed `link-cli` form. + +## How to Run + +All commands run through the `terminal` tool. The CLI auto-detects non-TTY callers and emits compact `toon` output by default — fine for the model. Pass `--format json` if a step needs structured fields. + +Discover commands: `link-cli --llms-full`. +Get a command's schema before invoking: `link-cli --schema`. + +## Procedure + +### 1. Check / establish auth + +``` +link-cli auth status +``` + +If not authenticated, log in with a clear client name (this label shows in the user's Link app): + +``` +link-cli auth login --client-name "Hermes" --interval 5 --timeout 300 +``` + +The `--interval`/`--timeout` form polls inline so the agent doesn't need to manage a `_next` step. Print the verification URL + phrase to the user and wait for the CLI to return. + +**Do not proceed past this step until `auth status` confirms login.** + +### 2. Evaluate the merchant before creating a spend request + +Decide the credential type: + +| Merchant surface | `--credential-type` | +|---|---| +| Standard web checkout form / Stripe Elements | `card` (default) | +| Returns HTTP 402 with `method="stripe"` in `www-authenticate` | `shared_payment_token` | +| Returns HTTP 402 without `method="stripe"` | unsupported — stop | + +For 402 responses, do NOT decode the challenge manually. Pass the raw header: + +``` +link-cli mpp decode --challenge '' +``` + +This validates the challenge and extracts the network ID + decoded request body. + +### 3. List payment methods + shipping + +``` +link-cli payment-methods list +link-cli shipping-address list +``` + +Use the first entry unless the user specifies otherwise. The `id` from `payment-methods list` is the `--payment-method-id` in the next step. + +### 4. Create the spend request + +Confirm the final total with the user before issuing this command. Amounts are in cents. + +``` +link-cli spend-request create \ + --payment-method-id \ + --merchant-name "" \ + --merchant-url "" \ + --context "" \ + --amount \ + --line-item "name:,unit_amount:,quantity:1" \ + --total "type:total,display_text:Total,amount:" \ + --request-approval +``` + +For MPP merchants add `--credential-type shared_payment_token`. + +`--request-approval` pings the user's Link app and polls until they approve or deny. The CLI exits non-zero on deny / timeout. + +### 5. Retrieve the credential — SECURELY + +**Do not print card details to stdout.** Use `--output-file` so the PAN never enters the agent's transcript or logs: + +``` +link-cli spend-request retrieve \ + --include card \ + --output-file /tmp/link-card.json \ + --format json +``` + +The file is written with `0600` perms; stdout shows only redacted fields (brand, last4, expiry) plus a `card_output_file` path. + +### 6. Use the credential + +- For web checkout: hand the file path to the user, OR pass it to a browser-driving tool that fills the form directly from disk. Never `read_file` or `cat` the card file into the agent's reasoning context. +- For MPP merchants: + + ``` + link-cli mpp pay \ + --spend-request-id \ + --method POST \ + --data '' + ``` + +### 7. Clean up + +Delete the card file as soon as the purchase is done: + +``` +rm -f /tmp/link-card.json +``` + +## Optional: run as an MCP server instead + +`@stripe/link-cli --mcp` exposes the same commands as MCP tools over stdio. To register it with Hermes' native MCP: + +``` +hermes mcp add stripe-link --command "npx" --args "@stripe/link-cli --mcp" +``` + +Then `hermes mcp list` should show `stripe-link`. The same approval rules apply — MCP doesn't bypass the Link app approval step. + +## Pitfalls + +- **US-only.** Outside the US, `auth login` will fail. Tell the user, don't keep retrying. +- **Card PAN must never enter agent context.** Use `--output-file` every time. If you've already retrieved without it, immediately `link-cli auth logout` is not enough — the card is one-time-use but rotate hygiene matters. +- **`--request-approval` blocks until the user acts.** If the user is asleep, the CLI will hit its timeout. Set expectations. +- **Multi-step `_next` commands.** Some commands return `_next.command` that must be executed to continue. When in doubt, prefer the inline-polling flags (`--interval`/`--timeout`). +- **Output format defaults to `toon`** in non-TTY mode. Fine for prose, but if a downstream step needs to parse a specific field, pass `--format json`. +- **Don't default to `card`.** The merchant-evaluation step (Section 2) exists because picking the wrong credential type fails the purchase silently or leaks more data than needed. + +## Verification + +``` +link-cli --version && link-cli auth status +``` + +Exit code 0 means installed and logged in. diff --git a/optional-skills/payments/stripe-projects/SKILL.md b/optional-skills/payments/stripe-projects/SKILL.md new file mode 100644 index 00000000000..d1b30d89875 --- /dev/null +++ b/optional-skills/payments/stripe-projects/SKILL.md @@ -0,0 +1,120 @@ +--- +name: stripe-projects +description: Provision SaaS services + sync creds via Stripe Projects. +version: 0.1.0 +author: Teknium (teknium1), Hermes Agent +license: MIT +platforms: [linux, macos] +metadata: + hermes: + tags: [Payments, Stripe, Projects, Provisioning, Infrastructure] + related_skills: [stripe-link-cli, mpp-agent] +--- + +# Stripe Projects Skill + +Wraps the [Stripe Projects](https://projects.dev) CLI plugin so Hermes can provision SaaS services (Neon, Twilio, Vercel, etc.), generate and sync credentials into the user's `.env`, and manage billing across providers from one place. + +Gated `[linux, macos]` while the broader payments cluster matures on Windows. The Stripe CLI itself is cross-platform; this gate is a posture for the cluster, not a hard limit. + +## When to Use + +Trigger phrases: + +- "set up ", "provision ", "create a database" +- "give me a for this project" +- "manage my stack credentials", "rotate this key", "upgrade my plan" +- "what providers can I add?" + +If the user already has the service set up manually and just wants to use it, this skill is not the right entry point. + +## Prerequisites + +- Stripe CLI installed (Homebrew on macOS, package manager on Linux, or download from https://docs.stripe.com/stripe-cli/install) +- Stripe Projects plugin installed +- A Stripe account, logged in via `stripe login` + +## Install + +macOS: + +``` +brew install stripe/stripe-cli/stripe +stripe plugin install projects +``` + +Linux: follow the platform-specific install at https://docs.stripe.com/stripe-cli/install, then: + +``` +stripe plugin install projects +``` + +## How to Run + +All commands run through the `terminal` tool from inside the user's project directory (the CLI writes `.env` and `.projects/vault/vault.json` into the CWD). + +## Procedure + +### 1. Initialize the project + +``` +cd +stripe projects init +``` + +This creates `.projects/vault/vault.json` (encrypted credential store) and prepares the project to receive providers. + +### 2. Discover available providers + +``` +stripe projects catalog +``` + +Lists every provider Stripe Projects supports — databases, hosting, auth, AI, analytics, messaging, etc. + +### 3. Add a service + +``` +stripe projects add / +``` + +Examples: + +- `stripe projects add neon/postgres` +- `stripe projects add twilio/sms` +- `stripe projects add runloop/sandbox` + +The CLI provisions the service in the user's own account with the provider, generates credentials, syncs them into `.env`, and records the resource in the vault. The user may need to confirm a tier selection or pricing prompt. + +### 4. Verify + +``` +stripe projects list +``` + +Should show the newly added provider and its `.env` keys. + +### 5. Manage / upgrade / remove + +``` +stripe projects upgrade # tier change +stripe projects remove # deprovision +stripe projects rotate # rotate credentials +``` + +## Pitfalls + +- **`.env` writes are real writes.** The CLI appends to whatever `.env` is in the project root. If the user's `.env` is gitignored (normal), the keys land safely; if not, this skill could be a credential-leak vector. Always check `.gitignore` first. +- **Per-project state.** `.projects/vault/vault.json` is per-project. Provisioning the same service in two different projects creates two separate resources — and two bills. +- **Billing happens on Stripe's side.** Tier prompts during `add`/`upgrade` are real charges; surface them to the user before confirming. +- **Provider availability changes.** The catalog grows; if a provider the user names isn't listed, `stripe projects catalog | grep ` first instead of failing the `add` call. +- **Credentials in vault are encrypted but `.env` is plaintext.** Standard `.env` hygiene applies — never commit it. +- **Removing a service does NOT always destroy the underlying resource.** Some providers leave a paused/dormant resource behind. Check the provider's own dashboard after `remove` for high-cost services (managed databases especially). + +## Verification + +``` +stripe projects --version && stripe projects list +``` + +Exit code 0 inside an initialized project means the plugin is healthy. diff --git a/website/docs/reference/optional-skills-catalog.md b/website/docs/reference/optional-skills-catalog.md index 5e44cba8eb4..89a4f47fe87 100644 --- a/website/docs/reference/optional-skills-catalog.md +++ b/website/docs/reference/optional-skills-catalog.md @@ -162,6 +162,14 @@ hermes skills uninstall | [**unsloth**](/docs/user-guide/skills/optional/mlops/mlops-training-unsloth) | Unsloth: 2-5x faster LoRA/QLoRA fine-tuning, less VRAM. | | [**whisper**](/docs/user-guide/skills/optional/mlops/mlops-whisper) | OpenAI's general-purpose speech recognition model. Supports 99 languages, transcription, translation to English, and language identification. Six model sizes from tiny (39M params) to large (1550M params). Use for speech-to-text, podcast... | +## payments + +| Skill | Description | +|-------|-------------| +| [**mpp-agent**](/docs/user-guide/skills/optional/payments/payments-mpp-agent) | Pay HTTP 402 APIs via Machine Payments Protocol (MPP). | +| [**stripe-link-cli**](/docs/user-guide/skills/optional/payments/payments-stripe-link-cli) | Agent payments via Stripe Link — cards, SPT, approvals. | +| [**stripe-projects**](/docs/user-guide/skills/optional/payments/payments-stripe-projects) | Provision SaaS services + sync creds via Stripe Projects. | + ## productivity | Skill | Description | diff --git a/website/docs/user-guide/skills/optional/payments/payments-mpp-agent.md b/website/docs/user-guide/skills/optional/payments/payments-mpp-agent.md new file mode 100644 index 00000000000..ee2ff286e25 --- /dev/null +++ b/website/docs/user-guide/skills/optional/payments/payments-mpp-agent.md @@ -0,0 +1,142 @@ +--- +title: "Mpp Agent — Pay HTTP 402 APIs via Machine Payments Protocol (MPP)" +sidebar_label: "Mpp Agent" +description: "Pay HTTP 402 APIs via Machine Payments Protocol (MPP)" +--- + +{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} + +# Mpp Agent + +Pay HTTP 402 APIs via Machine Payments Protocol (MPP). + +## Skill metadata + +| | | +|---|---| +| Source | Optional — install with `hermes skills install official/payments/mpp-agent` | +| Path | `optional-skills/payments/mpp-agent` | +| Version | `0.1.0` | +| Author | Teknium (teknium1), Hermes Agent | +| License | MIT | +| Platforms | linux, macos | +| Tags | `Payments`, `MPP`, `HTTP-402`, `Tempo`, `Stripe` | +| Related skills | [`stripe-link-cli`](/docs/user-guide/skills/optional/payments/payments-stripe-link-cli), [`stripe-projects`](/docs/user-guide/skills/optional/payments/payments-stripe-projects) | + +## Reference: full SKILL.md + +:::info +The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active. +::: + +# MPP Agent Skill + +Wraps the Machine Payments Protocol (MPP, https://mpp.dev) clients so Hermes can pay for per-request API access against servers that respond with `HTTP 402 Payment Required`. + +Three client options, all distributed via npm. Pick the lightest one that solves the user's need. Gated `[linux, macos]` while the broader payments tooling matures on Windows. + +## When to Use + +- A merchant API returns `HTTP 402` with a `www-authenticate` header — and the user wants to actually pay it, not just log the response. +- The user asks to "pay per request", "set up an agent wallet", "use Tempo / Privy / AgentCash", or wants to discover MPP-priced services. +- A Stripe Link spend has produced a Shared Payment Token (SPT) and the agent needs to attach it to the 402 challenge — in that flow, prefer `link-cli mpp pay` (see the `stripe-link-cli` skill). + +## Choosing a client + +| Tool | When | Setup | +|---|---|---| +| `link-cli` | User already has Stripe Link set up, or the 402 challenge advertises `method="stripe"` | see the `stripe-link-cli` skill | +| Tempo Wallet | MPP services with spend controls, service discovery | `tempo wallet login` | +| Privy Agent CLI | Multi-chain wallets, browser-based funding | `privy-agent-wallets login` | +| AgentCash | 300+ pre-priced APIs via one USDC.e balance | `npx agentcash onboard` | +| `mppx` | Dev + debugging, smallest dep surface | `npm install -g mppx` then `mppx account create` | + +Default: if the user already has Stripe Link configured or the 402 challenge specifies `method="stripe"`, use `link-cli mpp pay` (the `stripe-link-cli` skill). Otherwise `mppx` for one-off paid calls and debugging, and Tempo Wallet when the user wants persistent spend controls. + +## Prerequisites + +- Node.js 20+ on `PATH` +- A funded wallet (Tempo / Privy / AgentCash) OR an `mppx` account +- For Tempo / Privy / AgentCash: follow their respective onboarding skills: + - `https://tempo.xyz/SKILL.md` + - `https://agents.privy.io/skill.md` + - `https://agentcash.dev/skill.md` + +Use `web_extract` to fetch any of those SKILL.md files if the user picks one. + +## Procedure (mppx, fastest path) + +Run all commands through the `terminal` tool. + +### 1. Install + create an account + +``` +npm install -g mppx +mppx account create +``` + +Store the resulting account credentials wherever the CLI tells you (the CLI writes them under its own config — do not paste them into the agent transcript). + +### 2. Inspect the merchant's 402 challenge + +If the user gives you a URL, probe it first to confirm it actually speaks MPP: + +``` +curl -i +``` + +A real MPP 402 looks like: + +``` +HTTP/1.1 402 Payment Required +www-authenticate: tempo amount=0.1 currency=... +``` + +### 3. Pay the request + +``` +mppx +``` + +For non-GET methods or request bodies: + +``` +mppx --method POST --data '' +``` + +`mppx` handles the 402 challenge/credential dance automatically and prints the merchant's actual response on success. + +### 4. Verify the receipt + +`mppx` attaches the receipt header automatically. To inspect: + +``` +mppx -v +``` + +## Procedure (Tempo Wallet) + +The Tempo Wallet skill at https://tempo.xyz/SKILL.md is the canonical reference; fetch it with `web_extract` and follow it. Headline: + +``` +tempo wallet login +tempo wallet pay +``` + +Spend controls and service discovery live in the wallet UI at https://wallet.tempo.xyz. + +## Pitfalls + +- **`HTTP 402` without `method="stripe"` cannot be paid by Stripe Link.** If the challenge advertises only Tempo / other methods, use `mppx` (or whichever wallet matches) — Link will reject it. Conversely, if it advertises `method="stripe"`, prefer Link via the `stripe-link-cli` skill so the spend goes through the user's approved card. +- **Multiple challenges in one header.** `www-authenticate` may list several methods (e.g. `tempo, stripe`). The Link CLI's `mpp decode` will pick the Stripe one; `mppx` will pick Tempo. There's no single "right" client — pick by which wallet the user has funded. +- **Zero-amount challenges.** Some MPP endpoints charge `$0.00` and just want a proof credential. These work without a funded wallet. Don't refuse them as "broken." +- **Wallet keys never enter agent context.** All four clients store keys under their own config dirs (or generate per-session ephemeral keypairs, in Privy's case). Do not `cat`/`read_file` them. +- **Server-side MPP is a different skill.** If the user wants to ADD 402 to their own API, this skill is wrong — point them at https://mpp.dev/quickstart/server and the `mppx/nextjs` / `mppx/hono` / `mppx/express` / `mppx/elysia` middlewares. A dedicated `mpp-server` skill may land later. + +## Verification + +``` +mppx --version && mppx account list +``` + +Exit code 0 means installed and an account exists. diff --git a/website/docs/user-guide/skills/optional/payments/payments-stripe-link-cli.md b/website/docs/user-guide/skills/optional/payments/payments-stripe-link-cli.md new file mode 100644 index 00000000000..fdabbab6cb1 --- /dev/null +++ b/website/docs/user-guide/skills/optional/payments/payments-stripe-link-cli.md @@ -0,0 +1,202 @@ +--- +title: "Stripe Link Cli — Agent payments via Stripe Link — cards, SPT, approvals" +sidebar_label: "Stripe Link Cli" +description: "Agent payments via Stripe Link — cards, SPT, approvals" +--- + +{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} + +# Stripe Link Cli + +Agent payments via Stripe Link — cards, SPT, approvals. + +## Skill metadata + +| | | +|---|---| +| Source | Optional — install with `hermes skills install official/payments/stripe-link-cli` | +| Path | `optional-skills/payments/stripe-link-cli` | +| Version | `0.1.0` | +| Author | Teknium (teknium1), Hermes Agent | +| License | MIT | +| Platforms | linux, macos | +| Tags | `Payments`, `Stripe`, `Link`, `Checkout`, `MPP` | +| Related skills | [`mpp-agent`](/docs/user-guide/skills/optional/payments/payments-mpp-agent), [`stripe-projects`](/docs/user-guide/skills/optional/payments/payments-stripe-projects) | + +## Reference: full SKILL.md + +:::info +The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active. +::: + +# Stripe Link CLI Skill + +Wraps [@stripe/link-cli](https://github.com/stripe/link-cli) so Hermes can complete purchases on the user's behalf using one-time-use virtual cards or Shared Payment Tokens (SPT). Every spend is gated by an in-app approval in the Link mobile/web app — Hermes cannot self-approve. + +US-only at the moment (Link account requirement). Windows is not supported by the upstream CLI — this skill is gated `[linux, macos]`. + +## When to Use + +Trigger phrases: + +- "buy X", "pay for X", "make a purchase", "complete checkout" +- "get me a card", "I need a payment method" +- "log in to Link", "connect my Link wallet" +- HTTP 402 response from a merchant API with `www-authenticate: ... method="stripe"` + +If the user wants a paid API call (HTTP 402, no checkout form), the `card` path is wrong — use SPT via this same skill, or hand off to the `mpp-agent` skill. + +## Prerequisites + +- Node.js 20+ available on `PATH` (`node --version`) +- US-based (Link account requirement) + +The Link account, payment method, and spend-approval app do NOT need to be set up before Hermes attempts to pay — the CLI walks the user through them on first run: + +- A Link account at https://app.link.com — created/linked during first `link-cli` auth +- At least one payment method — added during first run at https://app.link.com/wallet +- The Link mobile/web app — opened to approve the first spend request when it's made + +No env vars required — auth state is stored locally by the CLI under its own config directory. + +## Install + +Install once, globally: + +``` +npm install -g @stripe/link-cli +``` + +Or invoke ad-hoc via `npx @stripe/link-cli`. The skill below uses the installed `link-cli` form. + +## How to Run + +All commands run through the `terminal` tool. The CLI auto-detects non-TTY callers and emits compact `toon` output by default — fine for the model. Pass `--format json` if a step needs structured fields. + +Discover commands: `link-cli --llms-full`. +Get a command's schema before invoking: `link-cli --schema`. + +## Procedure + +### 1. Check / establish auth + +``` +link-cli auth status +``` + +If not authenticated, log in with a clear client name (this label shows in the user's Link app): + +``` +link-cli auth login --client-name "Hermes" --interval 5 --timeout 300 +``` + +The `--interval`/`--timeout` form polls inline so the agent doesn't need to manage a `_next` step. Print the verification URL + phrase to the user and wait for the CLI to return. + +**Do not proceed past this step until `auth status` confirms login.** + +### 2. Evaluate the merchant before creating a spend request + +Decide the credential type: + +| Merchant surface | `--credential-type` | +|---|---| +| Standard web checkout form / Stripe Elements | `card` (default) | +| Returns HTTP 402 with `method="stripe"` in `www-authenticate` | `shared_payment_token` | +| Returns HTTP 402 without `method="stripe"` | unsupported — stop | + +For 402 responses, do NOT decode the challenge manually. Pass the raw header: + +``` +link-cli mpp decode --challenge '' +``` + +This validates the challenge and extracts the network ID + decoded request body. + +### 3. List payment methods + shipping + +``` +link-cli payment-methods list +link-cli shipping-address list +``` + +Use the first entry unless the user specifies otherwise. The `id` from `payment-methods list` is the `--payment-method-id` in the next step. + +### 4. Create the spend request + +Confirm the final total with the user before issuing this command. Amounts are in cents. + +``` +link-cli spend-request create \ + --payment-method-id \ + --merchant-name "" \ + --merchant-url "" \ + --context "" \ + --amount \ + --line-item "name:,unit_amount:,quantity:1" \ + --total "type:total,display_text:Total,amount:" \ + --request-approval +``` + +For MPP merchants add `--credential-type shared_payment_token`. + +`--request-approval` pings the user's Link app and polls until they approve or deny. The CLI exits non-zero on deny / timeout. + +### 5. Retrieve the credential — SECURELY + +**Do not print card details to stdout.** Use `--output-file` so the PAN never enters the agent's transcript or logs: + +``` +link-cli spend-request retrieve \ + --include card \ + --output-file /tmp/link-card.json \ + --format json +``` + +The file is written with `0600` perms; stdout shows only redacted fields (brand, last4, expiry) plus a `card_output_file` path. + +### 6. Use the credential + +- For web checkout: hand the file path to the user, OR pass it to a browser-driving tool that fills the form directly from disk. Never `read_file` or `cat` the card file into the agent's reasoning context. +- For MPP merchants: + + ``` + link-cli mpp pay \ + --spend-request-id \ + --method POST \ + --data '' + ``` + +### 7. Clean up + +Delete the card file as soon as the purchase is done: + +``` +rm -f /tmp/link-card.json +``` + +## Optional: run as an MCP server instead + +`@stripe/link-cli --mcp` exposes the same commands as MCP tools over stdio. To register it with Hermes' native MCP: + +``` +hermes mcp add stripe-link --command "npx" --args "@stripe/link-cli --mcp" +``` + +Then `hermes mcp list` should show `stripe-link`. The same approval rules apply — MCP doesn't bypass the Link app approval step. + +## Pitfalls + +- **US-only.** Outside the US, `auth login` will fail. Tell the user, don't keep retrying. +- **Card PAN must never enter agent context.** Use `--output-file` every time. If you've already retrieved without it, immediately `link-cli auth logout` is not enough — the card is one-time-use but rotate hygiene matters. +- **`--request-approval` blocks until the user acts.** If the user is asleep, the CLI will hit its timeout. Set expectations. +- **Multi-step `_next` commands.** Some commands return `_next.command` that must be executed to continue. When in doubt, prefer the inline-polling flags (`--interval`/`--timeout`). +- **Output format defaults to `toon`** in non-TTY mode. Fine for prose, but if a downstream step needs to parse a specific field, pass `--format json`. +- **Don't default to `card`.** The merchant-evaluation step (Section 2) exists because picking the wrong credential type fails the purchase silently or leaks more data than needed. + +## Verification + +``` +link-cli --version && link-cli auth status +``` + +Exit code 0 means installed and logged in. diff --git a/website/docs/user-guide/skills/optional/payments/payments-stripe-projects.md b/website/docs/user-guide/skills/optional/payments/payments-stripe-projects.md new file mode 100644 index 00000000000..5ee426361a2 --- /dev/null +++ b/website/docs/user-guide/skills/optional/payments/payments-stripe-projects.md @@ -0,0 +1,138 @@ +--- +title: "Stripe Projects — Provision SaaS services + sync creds via Stripe Projects" +sidebar_label: "Stripe Projects" +description: "Provision SaaS services + sync creds via Stripe Projects" +--- + +{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} + +# Stripe Projects + +Provision SaaS services + sync creds via Stripe Projects. + +## Skill metadata + +| | | +|---|---| +| Source | Optional — install with `hermes skills install official/payments/stripe-projects` | +| Path | `optional-skills/payments/stripe-projects` | +| Version | `0.1.0` | +| Author | Teknium (teknium1), Hermes Agent | +| License | MIT | +| Platforms | linux, macos | +| Tags | `Payments`, `Stripe`, `Projects`, `Provisioning`, `Infrastructure` | +| Related skills | [`stripe-link-cli`](/docs/user-guide/skills/optional/payments/payments-stripe-link-cli), [`mpp-agent`](/docs/user-guide/skills/optional/payments/payments-mpp-agent) | + +## Reference: full SKILL.md + +:::info +The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active. +::: + +# Stripe Projects Skill + +Wraps the [Stripe Projects](https://projects.dev) CLI plugin so Hermes can provision SaaS services (Neon, Twilio, Vercel, etc.), generate and sync credentials into the user's `.env`, and manage billing across providers from one place. + +Gated `[linux, macos]` while the broader payments cluster matures on Windows. The Stripe CLI itself is cross-platform; this gate is a posture for the cluster, not a hard limit. + +## When to Use + +Trigger phrases: + +- "set up <provider>", "provision <Neon|Twilio|Vercel|...>", "create a database" +- "give me a <Postgres|Redis|Twilio number|...> for this project" +- "manage my stack credentials", "rotate this key", "upgrade my plan" +- "what providers can I add?" + +If the user already has the service set up manually and just wants to use it, this skill is not the right entry point. + +## Prerequisites + +- Stripe CLI installed (Homebrew on macOS, package manager on Linux, or download from https://docs.stripe.com/stripe-cli/install) +- Stripe Projects plugin installed +- A Stripe account, logged in via `stripe login` + +## Install + +macOS: + +``` +brew install stripe/stripe-cli/stripe +stripe plugin install projects +``` + +Linux: follow the platform-specific install at https://docs.stripe.com/stripe-cli/install, then: + +``` +stripe plugin install projects +``` + +## How to Run + +All commands run through the `terminal` tool from inside the user's project directory (the CLI writes `.env` and `.projects/vault/vault.json` into the CWD). + +## Procedure + +### 1. Initialize the project + +``` +cd +stripe projects init +``` + +This creates `.projects/vault/vault.json` (encrypted credential store) and prepares the project to receive providers. + +### 2. Discover available providers + +``` +stripe projects catalog +``` + +Lists every provider Stripe Projects supports — databases, hosting, auth, AI, analytics, messaging, etc. + +### 3. Add a service + +``` +stripe projects add / +``` + +Examples: + +- `stripe projects add neon/postgres` +- `stripe projects add twilio/sms` +- `stripe projects add runloop/sandbox` + +The CLI provisions the service in the user's own account with the provider, generates credentials, syncs them into `.env`, and records the resource in the vault. The user may need to confirm a tier selection or pricing prompt. + +### 4. Verify + +``` +stripe projects list +``` + +Should show the newly added provider and its `.env` keys. + +### 5. Manage / upgrade / remove + +``` +stripe projects upgrade # tier change +stripe projects remove # deprovision +stripe projects rotate # rotate credentials +``` + +## Pitfalls + +- **`.env` writes are real writes.** The CLI appends to whatever `.env` is in the project root. If the user's `.env` is gitignored (normal), the keys land safely; if not, this skill could be a credential-leak vector. Always check `.gitignore` first. +- **Per-project state.** `.projects/vault/vault.json` is per-project. Provisioning the same service in two different projects creates two separate resources — and two bills. +- **Billing happens on Stripe's side.** Tier prompts during `add`/`upgrade` are real charges; surface them to the user before confirming. +- **Provider availability changes.** The catalog grows; if a provider the user names isn't listed, `stripe projects catalog | grep ` first instead of failing the `add` call. +- **Credentials in vault are encrypted but `.env` is plaintext.** Standard `.env` hygiene applies — never commit it. +- **Removing a service does NOT always destroy the underlying resource.** Some providers leave a paused/dormant resource behind. Check the provider's own dashboard after `remove` for high-cost services (managed databases especially). + +## Verification + +``` +stripe projects --version && stripe projects list +``` + +Exit code 0 inside an initialized project means the plugin is healthy. diff --git a/website/sidebars.ts b/website/sidebars.ts index 9b45991a18f..af12e6b8830 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -150,6 +150,7 @@ const sidebars: SidebarsConfig = { 'user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code', 'user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex', 'user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent', + 'user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-kanban-codex-lane', 'user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode', ], }, @@ -518,6 +519,17 @@ const sidebars: SidebarsConfig = { 'user-guide/skills/optional/mlops/mlops-whisper', ], }, + { + type: 'category', + label: 'payments', + key: 'skills-optional-payments', + collapsed: true, + items: [ + 'user-guide/skills/optional/payments/payments-mpp-agent', + 'user-guide/skills/optional/payments/payments-stripe-link-cli', + 'user-guide/skills/optional/payments/payments-stripe-projects', + ], + }, { type: 'category', label: 'productivity',