@stripe/link-cli 0.4.0 → 0.4.2

package/README.md

@@ -71,6 +71,23 @@ The `--request-approval` flag triggers a push notification (or email) to the use
 
 Users can easily approve requests with the [Link app](https://link.com/download).
 
+#### Line items and totals
+
+`--line-item` and `--total` use repeatable `key:value` format.
+
+**`--line-item` keys:** `name` (required), `quantity`, `unit_amount`, `description`, `sku`, `url`, `image_url`, `product_url`
+
+```bash
+--line-item "name:Running Shoes,unit_amount:12000,quantity:1,description:Trail runners"
+```
+
+**`--total` keys:** `type` (required), `display_text` (required), `amount` (required)
+
+```bash
+--total "type:subtotal,display_text:Subtotal,amount:12000" \
+--total "type:total,display_text:Total,amount:12000"
+```
+
 #### 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, you can instead include `--credential-type "shared_payment_token"`. 
@@ -84,6 +101,14 @@ link-cli spend-request retrieve lsrq_001 --format json
 ```
 By default, retrieving a spend request will not include card details. Use the `--include=card` to see unmasked card details.
 
+For agent polling, pass `--interval` and optionally `--max-attempts`:
+
+```bash
+link-cli spend-request retrieve lsrq_001 --interval 2 --max-attempts 150 --format json
+```
+
+Polling exits successfully only after the request reaches a terminal status such as `approved`, `denied`, or `expired`. 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.
+
 If the merchant supports MPP, use `link-cli mpp pay` instead:
 
 ```bash

package/dist/cli.js

@@ -13590,8 +13590,13 @@ function parseKvString(raw) {
   }
   return result;
 }
-function formatZodError(err, prefix) {
+function formatZodError(err, prefix, schema) {
+  const allowed = Object.keys(schema.shape);
   const messages = err.issues.map((issue) => {
+    if (issue.code === "unrecognized_keys") {
+      const keys = issue.keys.map((k) => `"${k}"`).join(", ");
+      return `${prefix}: unrecognized key ${keys}. Allowed keys: ${allowed.join(", ")}`;
+    }
     const key = issue.path[0]?.toString();
     return key ? `${prefix} ${key}: ${issue.message}` : `${prefix}: ${issue.message}`;
   });
@@ -13602,7 +13607,8 @@ function parseLineItemFlag(raw) {
   try {
     return LineItemSchema.parse(obj);
   } catch (err) {
-    if (err instanceof z5.ZodError) throw formatZodError(err, "Line item");
+    if (err instanceof z5.ZodError)
+      throw formatZodError(err, "Line item", LineItemSchema);
     throw err;
   }
 }
@@ -13611,7 +13617,8 @@ function parseTotalFlag(raw) {
   try {
     return TotalSchema.parse(obj);
   } catch (err) {
-    if (err instanceof z5.ZodError) throw formatZodError(err, "Total");
+    if (err instanceof z5.ZodError)
+      throw formatZodError(err, "Total", TotalSchema);
     throw err;
   }
 }
@@ -14199,19 +14206,27 @@ var createOptions = z6.object({
   context: z6.string().min(100).describe(
     "Min 100 chars \u2014 describe the purchase and rationale; the user reads this when approving"
   ),
-  lineItem: z6.array(z6.union([z6.string(), z6.record(z6.string(), z6.unknown())])).default([]).describe("Line item (repeatable, key:value format)"),
-  total: z6.array(z6.union([z6.string(), z6.record(z6.string(), z6.unknown())])).default([]).describe("Total (repeatable, key:value format)"),
+  lineItem: z6.array(z6.union([z6.string(), z6.record(z6.string(), z6.unknown())])).default([]).describe(
+    'Line item (repeatable, key:value format). Keys: name (required), quantity, unit_amount, description, sku, url, image_url, product_url. Example: "name:Shoes,unit_amount:5000,quantity:2"'
+  ),
+  total: z6.array(z6.union([z6.string(), z6.record(z6.string(), z6.unknown())])).default([]).describe(
+    'Total (repeatable, key:value format). Keys: type (required), display_text (required), amount (required). Example: "type:total,display_text:Total,amount:5000"'
+  ),
   requestApproval: z6.boolean().default(true).describe("Request approval and poll until approved/denied/expired"),
   test: z6.boolean().default(false).describe(
     "Use test mode (creates testmode credentials from test card data)"
   )
 });
 var retrieveOptions = z6.object({
-  timeout: z6.coerce.number().default(300).describe("Polling timeout in seconds"),
+  timeout: z6.coerce.number().default(300).describe(
+    "Polling timeout in seconds. When reached during active polling, exits non-zero with POLLING_TIMEOUT."
+  ),
   interval: z6.coerce.number().default(0).describe(
-    "Poll interval in seconds. When > 0, polls until status is terminal or timeout is reached, yielding status on each attempt."
+    "Poll interval in seconds. When > 0, polls until status is terminal, timeout is reached, or max attempts are exhausted."
+  ),
+  maxAttempts: z6.coerce.number().default(0).describe(
+    "Max poll attempts. 0 = unlimited. Exhaustion during active polling exits non-zero with POLLING_TIMEOUT."
   ),
-  maxAttempts: z6.coerce.number().default(0).describe("Max poll attempts. 0 = unlimited (use timeout instead)."),
   include: z6.array(z6.string()).default([]).describe("Include extra data (repeatable, e.g. --include card)")
 });
 var updateOptions = z6.object({
@@ -14221,8 +14236,12 @@ var updateOptions = z6.object({
   profileId: z6.string().optional().describe("Profile ID"),
   merchantId: z6.string().optional().describe("Merchant ID"),
   currency: z6.string().optional().describe("Currency code"),
-  lineItem: z6.array(z6.union([z6.string(), z6.record(z6.string(), z6.unknown())])).default([]).describe("Line item (repeatable, key:value format)"),
-  total: z6.array(z6.union([z6.string(), z6.record(z6.string(), z6.unknown())])).default([]).describe("Total (repeatable, key:value format)")
+  lineItem: z6.array(z6.union([z6.string(), z6.record(z6.string(), z6.unknown())])).default([]).describe(
+    'Line item (repeatable, key:value format). Keys: name (required), quantity, unit_amount, description, sku, url, image_url, product_url. Example: "name:Shoes,unit_amount:5000,quantity:2"'
+  ),
+  total: z6.array(z6.union([z6.string(), z6.record(z6.string(), z6.unknown())])).default([]).describe(
+    'Total (repeatable, key:value format). Keys: type (required), display_text (required), amount (required). Example: "type:total,display_text:Total,amount:5000"'
+  )
 });
 
 // src/commands/spend-request/update.tsx
@@ -14600,11 +14619,20 @@ function createSpendRequestCli(repository) {
           return;
         }
         attempts++;
-        const shouldStop = interval <= 0 || maxAttempts > 0 && attempts >= maxAttempts || Date.now() >= deadline;
-        if (shouldStop) {
+        if (interval <= 0) {
           yield request;
           return;
         }
+        const maxAttemptsExhausted = maxAttempts > 0 && attempts >= maxAttempts;
+        const timeoutReached = Date.now() >= deadline;
+        if (maxAttemptsExhausted || timeoutReached) {
+          const reason = maxAttemptsExhausted ? `max attempts (${maxAttempts}) exhausted` : `timeout (${timeout}s) reached`;
+          return c.error({
+            code: "POLLING_TIMEOUT",
+            message: `Polling stopped before spend request ${id} reached a terminal status: ${reason}; current status is ${request.status}.`,
+            retryable: true
+          });
+        }
         const snapshot = JSON.stringify(request);
         if (snapshot !== previousAttemptData) {
           previousAttemptData = snapshot;
@@ -14917,7 +14945,7 @@ var ResourceFactory = class {
 };
 
 // src/cli.tsx
-var cliVersion = "0.4.0";
+var cliVersion = "0.4.2";
 var buildNumber = "1";
 var cliName = "@stripe/link-cli";
 var defaultHeaders = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stripe/link-cli",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "type": "module",
   "bin": {
     "link-cli": "./dist/cli.js"
@@ -25,6 +25,7 @@
     "ink": "^5.2.1",
     "ink-spinner": "^5.0.0",
     "mppx": "^0.5.7",
+    "viem": "^2.47.5",
     "qrcode": "^1.5.4",
     "react": "^18.3.1",
     "update-notifier": "^7.3.1",