@stripe/link-cli 0.10.1 → 0.12.0

package/README.md

@@ -154,10 +154,52 @@ link-cli spend-request create ... \
 
 In MCP/agent mode, pass as a structured object.
 
+#### Metadata
+
+Attach arbitrary string data to a spend request with the repeatable `--metadata` flag (`key:value` format). Max 50 keys, key ≤ 40 chars, value ≤ 500 chars.
+
+```bash
+link-cli spend-request create ... \
+  --metadata "order_id:ord_123" \
+  --metadata "team:growth"
+```
+
+In MCP/agent mode, pass `metadata` as a structured `{ key: value }` object.
+
 #### Credential types
 
 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. 
@@ -199,6 +241,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
 ```
@@ -207,11 +250,15 @@ 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 status` includes an `update` field when a newer version is available:
+`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
 {
   "authenticated": true,
+  "scope": "userinfo:read payment_methods.agentic",
+  "authorization_details": [{ "type": "source", "actions": ["read"] }],
   "update": {
     "current_version": "0.1.2",
     "latest_version": "0.2.0",
@@ -220,6 +267,8 @@ With `--interval`, the login command yields the verification code immediately an
 }
 ```
 
+`scope` and `authorization_details` are only present when the token endpoint returned them.
+
 Set `NO_UPDATE_NOTIFIER=1` to suppress update checks (for example, in CI).
 
 All commands accept `--auth <path>` to store auth credentials in a specific file instead of the default location. `auth login` writes to this file; all other commands read from it. Useful for running multiple sessions with separate identities.
@@ -228,7 +277,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.