shopstack 0.3.1 → 0.3.3

package/README.md

@@ -6,9 +6,9 @@ guest restaurant reservations.
 ## Install
 
 ```bash
-npm install shopstack@0.3.1
+npm install shopstack@0.3.3
 # or
-npm install -g shopstack@0.3.1
+npm install -g shopstack@0.3.3
 ```
 
 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.3` with `shopstack-mcp@0.2.3`.
 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.3"],
       "env": {
         "SHOPSTACK_API_URL": "https://shopstack-release-preview.shopstack.workers.dev/v1",
         "SHOPSTACK_CONFIG_FILE": "/absolute/private/path/shopstack-config.json"
@@ -110,7 +110,7 @@ one MCP server and three focused skills:
 - `shopstack-checkout` for checkout creation and monitoring;
 - `shopstack-onboarding` for verified signup and private local profiles.
 
-The plugin pins `shopstack-mcp@0.2.1`, which installs the matching
+The plugin pins `shopstack-mcp@0.2.3`, which installs the matching
 reservation-capable `shopstack` client. Configure the API address
 before starting the plugin or use a profile already bound to that API. The existing top-level
 `SKILL.md` remains in the npm client package for compatibility.
@@ -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/SKILL.md

@@ -19,8 +19,8 @@ chat to fix an environment mismatch.
 For the JavaScript client and CLI:
 
 ```bash
-npm install shopstack@0.3.1
-npm install -g shopstack@0.3.1
+npm install shopstack@0.3.3
+npm install -g shopstack@0.3.3
 ```
 
 For MCP clients, configure the local stdio server:
@@ -30,7 +30,7 @@ For MCP clients, configure the local stdio server:
   "mcpServers": {
     "shopstack": {
       "command": "npx",
-      "args": ["-y", "shopstack-mcp@0.2.1"]
+      "args": ["-y", "shopstack-mcp@0.2.3"]
     }
   }
 }
@@ -113,7 +113,18 @@ shopstack connect list
 shopstack connect link
 ```
 
-Include `payment_provider: "link"` only when the active user's Link connection reports checkout-ready. Otherwise omit `payment_provider`. Shopstack will run until card entry and request one protected checkout-scoped card through the SDK or no-echo CLI prompt.
+When the user chooses Link, include `payment_provider: "link"` even if Link is
+not connected. Shopstack prepares the merchant checkout first. At card
+issuance, `required_input.type: "link"` supplies the exact sign-in or approval
+URL, amount, currency, and an optional verification phrase. Show those values
+and keep monitoring. Shopstack polls Link and resumes automatically; never ask
+the user to send a completion message. Link credential approval does not grant
+Shopstack final order approval.
+
+Omit `payment_provider` when the user wants to supply a card directly.
+Shopstack then requests protected checkout-scoped card input at the payment
+form through the SDK, CLI prompt, or live viewer. Connecting Link in advance
+with the commands above is optional.
 
 Never put card data in MCP arguments, natural-language messages, model output, logs, or ordinary CLI flags.
 
@@ -150,20 +161,25 @@ Run it with:
 shopstack checkout run --file checkout.json
 ```
 
-Or create with MCP, then call `poll_checkout`. Display these authoritative fields to the user when they change:
+Or create with MCP, read with `poll_checkout`, and monitor changes with
+`wait_checkout_update` using the latest `presentation_revision`. Display these
+authoritative fields to the user when they change:
 
 - `status`: one of exactly `queued`, `started`, `help_required`, `approval_required`, `submitting`, `complete`, `failed`, `cancelled`;
 - `activity`: bounded present-tense display text;
 - `intent.name`, `intent.phase`, and `intent.updated_at`: bounded mechanical action progress with no arguments or reasoning;
-- `required_input`: a typed handoff such as protected payment-card input;
+- `required_input`: a typed handoff for Link or protected payment-card input;
 - `approval`: the exact amount-bound approval request when present.
 
-Poll every two seconds for `queued`, `started`, and `submitting`; every five seconds for `help_required` and `approval_required`; stop at `complete`, `failed`, or `cancelled`.
+Keep calling `wait_checkout_update` while Link sign-in or approval is pending;
+an unchanged response is not a failure. Stop at `complete`, `failed`, or
+`cancelled`. The CLI monitor follows changes automatically.
 
 ## Respond at typed boundaries
 
 - Use `GET/POST /v1/checkout/{id}/messages` only for ordinary missing information.
 - Use protected SDK/CLI payment input when `required_input.type` is `payment_card`.
+- Show the exact URL and keep monitoring when `required_input.type` is `link`.
 - Use only the dedicated payment-approval endpoint from a separately scoped trusted backend.
 - MCP and messages cannot approve payment and expose no approval tool.
 - Never infer approval from a user's conversational message.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shopstack",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "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