shopstack 0.3.1 → 0.3.2

package/README.md

@@ -6,9 +6,9 @@ guest restaurant reservations.
 ## Install
 
 ```bash
-npm install shopstack@0.3.1
+npm install shopstack@0.3.2
 # or
-npm install -g shopstack@0.3.1
+npm install -g shopstack@0.3.2
 ```
 
 Node.js 18 or newer is required.
@@ -18,7 +18,7 @@ WebSocket (Node.js 22 or newer). It reads the authenticated checkout resource
 after each notification. Older runtimes, or a failed socket connection, use the
 bounded HTTP update wait. The one-time socket token is never placed in a URL.
 
-This preview release pairs `shopstack@0.3.1` with `shopstack-mcp@0.2.1`.
+This preview release pairs `shopstack@0.3.2` with `shopstack-mcp@0.2.2`.
 Both packages use the `preview` distribution tag. The `latest` versions are
 unchanged. Use the exact versions above to install this release.
 
@@ -79,7 +79,7 @@ Configure any stdio MCP client to run:
   "mcpServers": {
     "shopstack": {
       "command": "npx",
-      "args": ["-y", "shopstack-mcp@0.2.1"],
+      "args": ["-y", "shopstack-mcp@0.2.2"],
       "env": {
         "SHOPSTACK_API_URL": "https://shopstack-release-preview.shopstack.workers.dev/v1",
         "SHOPSTACK_CONFIG_FILE": "/absolute/private/path/shopstack-config.json"
@@ -122,8 +122,12 @@ shopstack connect list
 shopstack connect link
 ```
 
-Link is currently the only persistent payment provider. Connecting it is
-optional.
+Link is currently the only persistent payment provider. Connecting it in advance
+is optional. Select `payment_provider: "link"` to prepare the cart first; at card
+issuance Shopstack returns the Link sign-in or approval URL and waits. After Link
+responds, checkout resumes automatically. No “done” message is needed. The CLI
+keeps watching; MCP agents use `wait_checkout_update` with the latest
+`presentation_revision`. Final order approval is still a separate step.
 
 ## Run a guest reservation
 
@@ -199,7 +203,7 @@ form, then asks for card details through a no-echo terminal prompt. Card data is
 sent only to the protected payment-details endpoint. The CLI separately shows
 the exact final amount and asks for approval before Shopstack can submit.
 
-To use an active Link connection, add `"payment_provider": "link"` to the
+To use Link, with or without a prior connection, add `"payment_provider": "link"` to the
 request.
 
 Card values are never accepted as command-line flags.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shopstack",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Shopstack API client and command-line checkout and reservation tools.",
   "type": "module",
   "exports": {

package/specs/openapi.json

@@ -2670,7 +2670,7 @@
           },
           "payment_provider": {
             "$ref": "#/components/schemas/PaymentProvider",
-            "description": "Optional. Select Link only when this user has an active Link connection; otherwise the checkout requests protected one-checkout card input at the payment form."
+            "description": "Optional. Select Link without connecting first. At card issuance the checkout returns a Link login or approval URL in required_input and waits. Omission requests protected one-checkout card input instead. Link approval does not approve final order submission."
           },
           "external_reference": {
             "type": "string",
@@ -2790,14 +2790,62 @@
         }
       },
       "RequiredInput": {
+        "oneOf": [
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "type"
+            ],
+            "properties": {
+              "type": {
+                "const": "payment_card"
+              }
+            }
+          },
+          {
+            "$ref": "#/components/schemas/LinkRequiredInput"
+          }
+        ]
+      },
+      "LinkRequiredInput": {
         "type": "object",
         "additionalProperties": false,
+        "description": "Owner-private Link login or credential approval. Open the exact URL or approve in Link. This does not approve Shopstack order submission. The checkout resumes automatically after Link responds.",
         "required": [
-          "type"
+          "type",
+          "action",
+          "url",
+          "amount_cents",
+          "currency"
         ],
         "properties": {
           "type": {
-            "const": "payment_card"
+            "const": "link"
+          },
+          "action": {
+            "enum": [
+              "connect",
+              "approve"
+            ]
+          },
+          "url": {
+            "type": "string",
+            "format": "uri",
+            "maxLength": 2048
+          },
+          "phrase": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 100
+          },
+          "amount_cents": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 500000
+          },
+          "currency": {
+            "$ref": "#/components/schemas/Currency"
           }
         }
       },

package/src/cli.js

@@ -649,6 +649,17 @@ export async function runCli(args, supplied = {}) {
           `[${checkout.status}]${intent} ${checkout.activity ?? ""}`.trimEnd() +
             "\n",
         );
+        if (checkout.required_input?.type === "link") {
+          const input = checkout.required_input;
+          dependencies.stderr.write(
+            `${input.action === "connect" ? "Connect Link" : "Approve in Link"}: ${input.url}\n` +
+              `Amount: ${input.currency} ${(input.amount_cents / 100).toFixed(2)}\n` +
+              (input.action === "connect" && input.phrase
+                ? `Code: ${input.phrase}\n`
+                : "") +
+              "The checkout resumes automatically. Final order approval is separate.\n",
+          );
+        }
       },
       approve: async (approval) => {
         const summary = [

package/src/client.d.ts

@@ -138,7 +138,17 @@ export interface Checkout {
   item_url: string;
   /** Present this exact owner-only URL verbatim. Never reconstruct its token. */
   live_view_url?: string;
-  required_input?: { type: "payment_card" };
+  required_input?:
+    | { type: "payment_card" }
+    | {
+        type: "link";
+        action: "connect" | "approve";
+        /** Owner-private Link URL. Present it verbatim; never reconstruct it. */
+        url: string;
+        phrase?: string;
+        amount_cents: number;
+        currency: string;
+      };
   approval?: PaymentApproval;
   result?: Record<string, unknown>;
   failure?: Record<string, unknown>;

package/src/client.js

@@ -576,7 +576,7 @@ export class ShopstackClient {
         current.intent?.name,
         current.intent?.phase,
         current.intent?.updated_at,
-        current.required_input?.type,
+        current.required_input,
         current.approval?.id,
       ]);
       if (fingerprint === progressFingerprint) return;
@@ -597,6 +597,12 @@ export class ShopstackClient {
         }
         checkout = await this.getCheckout(checkout.id);
         await publishProgress(checkout);
+        if (
+          checkout.required_input?.type === "link" &&
+          typeof options.onProgress !== "function"
+        ) {
+          return checkout;
+        }
         if (
           checkout.required_input?.type === "payment_card" &&
           handledPaymentRevision !== checkout.revision