@stripe/link-cli 0.15.1 → 0.17.0

package/README.md

@@ -310,6 +310,24 @@ card SpendRequest instead; do not create an LPT request.
 | Rolling creation rate | 200 per 60 days |
 
 
+Use `mpp pay` to complete purchases on merchants that use the [Machine Payments Protocol](https://mpp.dev). The spend request must use `credential_type: "shared_payment_token"` and you must approve it before paying. The SPT is one-time-use — if payment fails, create a new spend request.
+
+```bash
+link-cli mpp pay https://climate.stripe.dev/api/contribute \
+  --spend-request-id lsrq_001 \
+  --method POST \
+  --data '{"amount":100}' \
+  --header "X-Custom: value"
+```
+
+In agent mode (`--format json`), the full flow returns the payment continuation twice: as `_next.pay_argv` (`{ "command": "mpp", "args": [...] }`) and as `_next.pay_command`. Prefer `pay_argv` and invoke it directly, passing each `args` entry as its own process argument. The URL, body and headers can carry merchant-controlled text, so `pay_command` is shell-quoted for callers that must go through a shell — pass it to the shell verbatim, without unquoting or re-splitting it.
+
+Use `mpp decode` to validate a raw `WWW-Authenticate` header and extract the `network_id` needed for `shared_payment_token` spend requests:
+
+```bash
+link-cli mpp decode \
+  --challenge 'Payment id="ch_001", realm="merchant.example", method="stripe", intent="charge", request="..."'
+```
 
 ### Report outcomes
 

package/dist/cli.js

@@ -593,7 +593,9 @@ var BalancesResource = class extends BaseResource {
 var paymentMethodSchema = z2.looseObject({
   id: z2.string(),
   type: z2.string(),
-  is_default: z2.boolean()
+  is_default: z2.boolean(),
+  name: z2.string(),
+  nickname: z2.optional(z2.string().nullable())
 });
 var paymentMethodsResponseSchema = z2.looseObject({
   payment_details: z2.array(paymentMethodSchema)
@@ -800,11 +802,13 @@ var SpendRequestResource = class extends BaseResource {
     );
   }
   async update(id, params) {
+    const { approve, ...body } = params;
+    const url = approve ? `${this.endpoint}/${id}/update_delegated` : `${this.endpoint}/${id}`;
     const { status, data, rawBody } = await this.apiFetch({
       method: "POST",
-      url: `${this.endpoint}/${id}`,
+      url,
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(params)
+      body: JSON.stringify(body)
     });
     if (status < 200 || status >= 300) {
       this.throwApiError("update spend request", status, data, rawBody);
@@ -2799,7 +2803,7 @@ function buildHeaders(data, headers) {
     if (key) result[key] = value;
   }
   if (!Object.keys(result).some((key) => key.toLowerCase() === "user-agent")) {
-    result["User-Agent"] = `link-cli/${"0.15.1"}`;
+    result["User-Agent"] = `link-cli/${"0.17.0"}`;
   }
   return result;
 }
@@ -3658,6 +3662,21 @@ function createDemoCli(authRepo2, spendRequestRepo2, createPaymentMethodsResourc
 // src/commands/mpp/index.tsx
 import { Cli as Cli4, z as z14 } from "incur";
 
+// src/utils/shell-quote.ts
+var SAFE_RE = /^[A-Za-z0-9_@%+=:,./-]+$/;
+function shellQuote(value) {
+  if (value === "") {
+    return "''";
+  }
+  if (SAFE_RE.test(value)) {
+    return value;
+  }
+  return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+function shellCommand(parts) {
+  return parts.map(shellQuote).join(" ");
+}
+
 // src/commands/mpp/decode-view.tsx
 import { Box as Box10, Text as Text12 } from "ink";
 import { jsx as jsx14, jsxs as jsxs10 } from "react/jsx-runtime";
@@ -3829,20 +3848,22 @@ function createMppCli(repository, paymentMethodsFactory, authStorage2, envAccess
         request_approval: true,
         test: opts.test || void 0
       });
-      const nextFlags = [`--spend-request-id ${spendRequest.id}`];
-      if (method) nextFlags.push(`-X ${method}`);
-      if (data) nextFlags.push(`-d '${data}'`);
+      const nextArgs = ["pay", url, "--spend-request-id", spendRequest.id];
+      if (method) nextArgs.push("-X", method);
+      if (data) nextArgs.push("-d", data);
       if (headers) {
-        for (const h of headers) nextFlags.push(`-H '${h}'`);
+        for (const h of headers) nextArgs.push("-H", h);
       }
-      const nextCommand = `mpp pay ${url} ${nextFlags.join(" ")}`;
+      const nextCommand = `mpp ${shellCommand(nextArgs)}`;
+      const pollCommand = `spend-request retrieve ${shellQuote(spendRequest.id)} --interval 2 --max-attempts 300`;
       yield {
         ...spendRequest,
-        instruction: `Present the approval_url to the user and ask them to approve in the Link app. Then call \`spend-request retrieve ${spendRequest.id} --interval 2 --max-attempts 300\` to poll until approved. Once approved, run the _next.command to complete payment. Do not wait for the user to reply \u2014 start polling immediately.`,
+        instruction: `Present the approval_url to the user and ask them to approve in the Link app. Then call \`${pollCommand}\` to poll until approved. Once approved, run _next.pay_argv (preferred \u2014 invoke it directly without a shell) or _next.pay_command to complete payment. Do not wait for the user to reply \u2014 start polling immediately.`,
         _next: {
-          poll_command: `spend-request retrieve ${spendRequest.id} --interval 2 --max-attempts 300`,
+          poll_command: pollCommand,
           pay_command: nextCommand,
-          until: "status changes from pending_approval, then run pay_command"
+          pay_argv: { command: "mpp", args: nextArgs },
+          until: "status changes from pending_approval, then run pay_argv"
         }
       };
     }
@@ -4094,7 +4115,7 @@ var PaymentMethodsList = ({
   return /* @__PURE__ */ jsxs13(Box13, { flexDirection: "column", children: [
     /* @__PURE__ */ jsx19(Text15, { bold: true, children: "Payment Methods" }),
     /* @__PURE__ */ jsx19(Box13, { flexDirection: "column", marginTop: 1, children: methods.map((pm) => {
-      const label = pm.card_details?.brand ?? pm.bank_account_details?.bank_name ?? "Bank account";
+      const label = pm.name ?? pm.card_details?.brand ?? pm.bank_account_details?.bank_name ?? "Bank account";
       const last4 = pm.card_details?.last4 ?? pm.bank_account_details?.last4;
       const suffix = pm.nickname ? `(${pm.nickname})` : "";
       const agenticCap = pm.capabilities?.agentic_payments;
@@ -4920,6 +4941,7 @@ var CreateSpendRequest = ({
   repository,
   params,
   requestApproval = false,
+  approve = false,
   outputFile,
   force,
   onComplete
@@ -5058,7 +5080,7 @@ var CreateSpendRequest = ({
             result.status_details?.requires_action?.next_action ?? null
           );
           setStatus("requires_action");
-        } else if (requestApproval) {
+        } else if (requestApproval && result.status !== "approved") {
           setStatus("waiting");
         } else {
           setStatus("success");
@@ -5333,7 +5355,7 @@ var CreateSpendRequest = ({
           fileError
         ] })
       ] }),
-      /* @__PURE__ */ jsx27(AppDownloadQrCodes, {})
+      !approve && /* @__PURE__ */ jsx27(AppDownloadQrCodes, {})
     ] });
   }
   return /* @__PURE__ */ jsxs18(Fragment4, { children: [
@@ -6171,13 +6193,39 @@ var updateOptions = z19.object({
   ),
   total: z19.array(z19.union([z19.string(), z19.record(z19.string(), z19.unknown())])).default([]).describe(
     'Total (repeatable, key:value format). Keys: type (required; one of: subtotal, tax, total, items_base_amount, items_discount, discount, fulfillment, shipping, fee, gift_wrap, tip, store_credit), display_text (required), amount (required). Example: "type:total,display_text:Total,amount:5000"'
-  )
+  ),
+  approve: z19.boolean().default(false).describe("Use the delegated approval flow for this update")
 });
 
 // src/commands/spend-request/update.tsx
-import { Box as Box22, Text as Text24 } from "ink";
+import { Box as Box22, Text as Text24, useInput as useInput10 } from "ink";
 import Spinner14 from "ink-spinner";
-import { useCallback as useCallback11 } from "react";
+import { useCallback as useCallback11, useState as useState12 } from "react";
+
+// src/utils/poll-until-spend-request-update.ts
+async function pollUntilSpendRequestUpdate(repository, id, pendingAmount, options = {}) {
+  const pollIntervalMs = options.pollIntervalMs ?? 2e3;
+  const timeoutMs = options.timeoutMs ?? 3e5;
+  const startTime = Date.now();
+  while (true) {
+    if (Date.now() - startTime > timeoutMs) {
+      throw new Error("Spend request update polling timed out");
+    }
+    const request = await repository.retrieve(id);
+    if (!request) {
+      throw new Error(`Spend request ${id} not found`);
+    }
+    if (request.amount === pendingAmount) {
+      return { request, outcome: "approved" };
+    }
+    if (!request.approval_url) {
+      return { request, outcome: "denied" };
+    }
+    await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+  }
+}
+
+// src/commands/spend-request/update.tsx
 import { jsx as jsx31, jsxs as jsxs22 } from "react/jsx-runtime";
 var UpdateSpendRequest = ({
   repository,
@@ -6185,12 +6233,45 @@ var UpdateSpendRequest = ({
   params,
   onComplete
 }) => {
-  const action = useCallback11(
-    () => repository.update(id, params),
-    [repository, id, params]
+  const [pendingApproval, setPendingApproval] = useState12(
+    null
+  );
+  const action = useCallback11(async () => {
+    const request2 = await repository.update(id, params);
+    if (params.amount !== void 0 && request2.status === "approved" && request2.approval_url) {
+      setPendingApproval(request2);
+      return pollUntilSpendRequestUpdate(repository, id, params.amount);
+    }
+    return { request: request2, outcome: "updated" };
+  }, [repository, id, params]);
+  const handleComplete = useCallback11(
+    (result2) => onComplete(result2?.request ?? null),
+    [onComplete]
+  );
+  const {
+    status,
+    data: result,
+    error
+  } = useAsyncAction(action, handleComplete);
+  const request = result?.request ?? pendingApproval;
+  useInput10(
+    (_input, key) => {
+      if (key.return && pendingApproval?.approval_url) {
+        openUrl(pendingApproval.approval_url);
+      }
+    },
+    { isActive: status === "loading" && pendingApproval !== null }
   );
-  const { status, data: request, error } = useAsyncAction(action, onComplete);
   if (status === "loading") {
+    if (pendingApproval?.approval_url) {
+      return /* @__PURE__ */ jsx31(
+        ApprovalWaitingView,
+        {
+          status: "polling",
+          approvalUrl: pendingApproval.approval_url
+        }
+      );
+    }
     return /* @__PURE__ */ jsx31(Box22, { children: /* @__PURE__ */ jsxs22(Text24, { color: "cyan", children: [
       /* @__PURE__ */ jsx31(Spinner14, { type: "dots" }),
       " Updating spend request ",
@@ -6204,6 +6285,21 @@ var UpdateSpendRequest = ({
       /* @__PURE__ */ jsx31(Text24, { color: "red", children: error })
     ] });
   }
+  if (result?.outcome === "denied") {
+    return /* @__PURE__ */ jsxs22(Box22, { flexDirection: "column", children: [
+      /* @__PURE__ */ jsx31(Text24, { color: "yellow", children: "\u2717 Spend request update denied" }),
+      /* @__PURE__ */ jsxs22(Box22, { flexDirection: "column", marginTop: 1, paddingX: 2, children: [
+        /* @__PURE__ */ jsxs22(Text24, { children: [
+          "ID: ",
+          /* @__PURE__ */ jsx31(Text24, { bold: true, children: request?.id })
+        ] }),
+        /* @__PURE__ */ jsxs22(Text24, { children: [
+          "Amount: ",
+          /* @__PURE__ */ jsx31(Text24, { bold: true, children: request?.amount ?? "N/A" })
+        ] })
+      ] })
+    ] });
+  }
   return /* @__PURE__ */ jsxs22(Box22, { flexDirection: "column", children: [
     /* @__PURE__ */ jsx31(Text24, { color: "green", children: "\u2713 Spend request updated" }),
     /* @__PURE__ */ jsxs22(Box22, { flexDirection: "column", marginTop: 1, paddingX: 2, children: [
@@ -6218,10 +6314,7 @@ var UpdateSpendRequest = ({
       /* @__PURE__ */ jsxs22(Text24, { children: [
         "Amount:",
         " ",
-        /* @__PURE__ */ jsx31(Text24, { bold: true, children: (() => {
-          const t = request?.totals?.find((t2) => t2.type === "total");
-          return t ? String(t.amount) : "N/A";
-        })() })
+        /* @__PURE__ */ jsx31(Text24, { bold: true, children: request?.amount !== void 0 ? String(request.amount) : "N/A" })
       ] }),
       /* @__PURE__ */ jsxs22(Text24, { children: [
         "Merchant: ",
@@ -6243,9 +6336,9 @@ function buildRequiresActionResult(request) {
   const isAutoResume2 = nextAction?.resolution === "auto_resume";
   return {
     ...request,
-    instruction: isAutoResume2 ? `The spend request requires 3D Secure verification. Present action_url (${nextAction?.action_url}) to the user, then call \`spend-request retrieve ${request.id} --interval 2 --max-attempts 300\` to poll until it resolves. Do not create a new spend request \u2014 this one resumes automatically once the challenge is completed.` : `The spend request requires action (${nextAction?.type}): ${nextAction?.display_message}${nextAction?.action_url ? ` URL: ${nextAction.action_url}` : ""} Have the user complete this, then create a new spend request.`,
+    instruction: isAutoResume2 ? `The spend request requires 3D Secure verification. Present action_url (${nextAction?.action_url}) to the user, then call \`spend-request retrieve ${shellQuote(request.id)} --interval 2 --max-attempts 300\` to poll until it resolves. Do not create a new spend request \u2014 this one resumes automatically once the challenge is completed.` : `The spend request requires action (${nextAction?.type}): ${nextAction?.display_message}${nextAction?.action_url ? ` URL: ${nextAction.action_url}` : ""} Have the user complete this, then create a new spend request.`,
     _next: isAutoResume2 ? {
-      command: `spend-request retrieve ${request.id} --interval 2 --max-attempts 300`,
+      command: `spend-request retrieve ${shellQuote(request.id)} --interval 2 --max-attempts 300`,
       until: "status changes from requires_action"
     } : void 0
   };
@@ -6433,6 +6526,7 @@ function createSpendRequestCli(repository, authStorage2, envAccessToken2) {
               repository,
               params: createParams,
               requestApproval,
+              approve: opts.approve ? true : void 0,
               outputFile,
               force: forceOverwrite,
               onComplete: (result) => {
@@ -6503,9 +6597,9 @@ function createSpendRequestCli(repository, authStorage2, envAccessToken2) {
       }
       yield {
         ...created,
-        instruction: `Present the approval_url to the user and ask them to approve in the Link app. Then call \`spend-request retrieve ${created.id} --interval 2 --max-attempts 300\` to poll until approved. Do not wait for the user to reply \u2014 start polling immediately.`,
+        instruction: `Present the approval_url to the user and ask them to approve in the Link app. Then call \`spend-request retrieve ${shellQuote(created.id)} --interval 2 --max-attempts 300\` to poll until approved. Do not wait for the user to reply \u2014 start polling immediately.`,
         _next: {
-          command: `spend-request retrieve ${created.id} --interval 2 --max-attempts 300`,
+          command: `spend-request retrieve ${shellQuote(created.id)} --interval 2 --max-attempts 300`,
           until: "status changes from pending_approval"
         }
       };
@@ -6539,6 +6633,9 @@ function createSpendRequestCli(repository, authStorage2, envAccessToken2) {
         params.totals = opts.total.map(
           (item) => typeof item === "string" ? parseTotalFlag(item) : item
         );
+      if (opts.approve !== void 0) {
+        params.approve = opts.approve;
+      }
       if (!c.agent && !c.formatExplicit) {
         let capturedResult = null;
         return renderInteractive(
@@ -6616,9 +6713,9 @@ function createSpendRequestCli(repository, authStorage2, envAccessToken2) {
       }
       yield {
         ...approval,
-        instruction: `Present the approval_url to the user and ask them to approve in the Link app. Then call \`spend-request retrieve ${id} --interval 2 --max-attempts 300\` to poll until approved. Do not wait for the user to reply \u2014 start polling immediately.`,
+        instruction: `Present the approval_url to the user and ask them to approve in the Link app. Then call \`spend-request retrieve ${shellQuote(id)} --interval 2 --max-attempts 300\` to poll until approved. Do not wait for the user to reply \u2014 start polling immediately.`,
         _next: {
-          command: `spend-request retrieve ${id} --interval 2 --max-attempts 300`,
+          command: `spend-request retrieve ${shellQuote(id)} --interval 2 --max-attempts 300`,
           until: "status changes from pending_approval"
         }
       };
@@ -7580,7 +7677,7 @@ function cacheUpdateInfo(value, ttlMs = UPDATE_CACHE_TTL_MS) {
 }
 
 // src/cli.tsx
-var cliVersion = "0.15.1";
+var cliVersion = "0.17.0";
 var cliName = "@stripe/link-cli";
 var defaultHeaders = {
   "User-Agent": `link-cli/${cliVersion}`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stripe/link-cli",
-  "version": "0.15.1",
+  "version": "0.17.0",
   "type": "module",
   "bin": {
     "link-cli": "./dist/cli.js"
@@ -45,7 +45,7 @@
     "tsx": "^4.23.5",
     "typescript": "^5.9.3",
     "vitest": "^4.1.10",
-    "@stripe/link-sdk": "0.2.1",
+    "@stripe/link-sdk": "0.3.0",
     "@stripe/link-typescript-config": "0.0.0"
   },
   "scripts": {