@stripe/link-cli 0.11.0 → 0.13.0

package/README.md

@@ -124,6 +124,8 @@ The `--request-approval` flag triggers a push notification to the user for appro
 
 Easily approve requests with the [Link app](https://link.com/download).
 
+If the created spend request comes back with `status: "requires_action"`, no approval is needed yet — the payment method or account needs attention first. Check `status_details.requires_action.next_action` for `type`, `display_message`, `action_url`, and `resolution`. For 3D Secure (`resolution: "auto_resume"`), keep polling `spend-request retrieve` — the request resolves on its own once the challenge is completed. For any other resolution, complete the indicated action and create a new spend request.
+
 #### Line items and totals
 
 `--line-item` and `--total` use repeatable `key:value` format.
@@ -170,6 +172,36 @@ In MCP/agent mode, pass `metadata` as a structured `{ key: value }` object.
 
 By default, a spend request provisions a virtual card. For merchants that support the [Machine Payments Protocol](https://mpp.dev) (HTTP 402) and the Stripe payment method, instead pass `--credential-type "shared_payment_token"`. 
 
+#### Link Pay Token
+
+Some Stripe checkout pages expose an AI-agent steering block that supports a
+Link Pay Token (LPT). Inspect the checkout in a browser before creating the
+SpendRequest: enable the agent checkbox, then verify that both
+`input[name="link_pay_token"]` and
+`data-stripe-merchant-account="acct_..."` are present in the same Stripe
+frame.
+
+Create an LPT-bound request with the DOM-derived account ID. Do not pass
+`--merchant-name` or `--merchant-url`; Link resolves the canonical merchant
+identity from the account ID for the approval screen.
+
+```bash
+link-cli spend-request create \
+  --payment-method-id csmrpd_xxx \
+  --execution-method link_pay_token \
+  --merchant-account-id acct_... \
+  --context "Purchasing an item from the checkout the agent inspected. The user initiated this purchase through the shopping assistant." \
+  --amount 3500 \
+  --request-approval
+```
+
+LPT requests use the default `card` credential type and do not support
+`--test`, `--network-id`, or `shared_payment_token`. After approval, retrieve
+`--include link_pay_token` immediately before using it on the same checkout
+surface. Each returned LPT is valid for up to 30 minutes, or until the
+SpendRequest expires. If either DOM marker is absent, create a regular virtual
+card SpendRequest instead; do not create an LPT request.
+
 ### Execute payment
 
 The approved spend request includes a `card` object with `number`, `cvc`, `exp_month`, `exp_year`, `billing_address`, and `valid_until`. Enter these into the merchant's checkout form. 
@@ -193,7 +225,7 @@ For agent polling, pass `--interval` and optionally `--max-attempts`:
 link-cli spend-request retrieve lsrq_001 --interval 2 --max-attempts 300
 ```
 
-Polling exits successfully only after the request reaches a terminal status such as `approved`, `denied`, `expired`, or `canceled`. If polling reaches `--timeout` or exhausts `--max-attempts` while the request is still non-terminal, the command exits non-zero with `code: "POLLING_TIMEOUT"` so callers do not treat a still-pending request as complete.
+Polling exits successfully only after the request reaches a terminal status such as `approved`, `denied`, `expired`, or `canceled`. If the status becomes `requires_action`, behavior depends on `next_action.resolution`: `auto_resume` (used for 3D Secure) means polling continues automatically — the request resolves on its own once the user completes the challenge. Any other resolution stops polling immediately and the command exits with the `next_action` details instead of waiting for a terminal status; the caller must have the user act, then create a new spend request. If `--timeout` is reached or `--max-attempts` is exhausted while the request is still non-terminal, the command exits non-zero with `code: "POLLING_TIMEOUT"` so callers do not treat a still-pending request as complete.
 
 If the merchant supports MPP, use `link-cli mpp pay` instead:
 
@@ -211,6 +243,7 @@ link-cli mpp pay https://climate.stripe.dev/api/contribute \
 ```bash
 link-cli auth login --client-name "Claude Code"   # identify the connecting agent
 link-cli auth login --client-name "Claude Code" --interval 5 --timeout 300  # login + poll in one call
+link-cli auth upgrade --scope "userinfo:read spend_requests:approve"        # widen access to a superset
 link-cli auth status                               # check auth status
 link-cli auth logout                               # disconnect
 ```
@@ -219,6 +252,8 @@ When you provide `--client-name`, the Link app displays it when you approve the
 
 With `--interval`, the login command yields the verification code immediately and then polls inline until authenticated or timed out — no separate `auth status` call needed. This is recommended for agents that cannot relay the code while a separate polling command blocks their I/O channel.
 
+`auth upgrade` takes the same flags as `auth login` but is meant for widening access when you're already logged in. Unlike `auth login` — which stops with an "already logged in" message when a valid session exists — `auth upgrade` merges the flags you pass with your currently granted `scope` and `authorization_details` and starts a new approval for the **superset**, so you never accidentally drop access. If there's no valid session, it prints a warning and continues with just the access you requested. Your current session stays valid throughout the approval and is only replaced (and the old grant revoked) once you approve the new one — so abandoning the approval leaves your existing session untouched.
+
 `auth status` reports the `scope` and `authorization_details` the current session was granted (echoed by the token endpoint at login/refresh and stored in the credential file), and includes an `update` field when a newer version is available:
 
 ```json
@@ -244,7 +279,13 @@ All commands accept `--auth <path>` to store auth credentials in a specific file
 
 A spend request moves through: **create** → **request approval** → **approved** (with credentials).
 
-**Required fields for create:** `merchant_name`, `merchant_url`, `context`, `amount`. `payment_method_id` is optional — if omitted, your default payment method will be used, or the first eligible one if no default is set.
+**Required fields for a regular card create:** `merchant_name`, `merchant_url`,
+`context`, and `amount`. `payment_method_id` is optional — if omitted,
+your default payment method will be used, or the first eligible one if no
+default is set. Shared Payment Token requests instead require `network_id`;
+Link Pay Token requests require `execution_method=link_pay_token` and the
+DOM-derived `merchant_account_id`, and Link supplies their canonical merchant
+identity.
 
 **Constraints:** `context` must be at least 100 characters; `amount` must not exceed 500000 (cents); `currency` must be a 3-letter ISO code. The user has 10 minutes from when approval is requested to approve. Approved credentials (card or SPT) are valid for 12 hours from spend request creation.
 **Test mode:** Pass `--test` to create a testmode SpendRequest. A testmode SpendRequest will return test payment credentials (e.g test card `4000009990001984`) rather than a real payment credential. Testmode SpendRequests will not charge the underlying payment method of the SpendRequest. This is useful for development and integration testing without real payment methods.