shopstack 0.2.1 → 0.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shopstack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,6 @@
 # shopstack
 
-Dependency-free JavaScript client and CLI for Shopstack's asynchronous checkout API.
+JavaScript client and CLI for Shopstack's asynchronous checkout API.
 
 ## Install
 
@@ -12,8 +12,8 @@ npm install -g shopstack
 
 Node.js 18 or newer is required.
 
-The 0.2.1 source candidate defaults to Shopstack's currently deployed public staging API at
-`https://shopstack-staging.shopstack.workers.dev/v1`. Set
+The CLI and client default to Shopstack's production API at
+`https://api.shopstack.ai/v1`. Set
 `SHOPSTACK_API_URL` only when targeting a different Shopstack environment.
 
 ## Verified signup
@@ -68,7 +68,7 @@ phase. It deliberately has no card-input or payment-approval tool.
 
 The canonical agent skill ships as `SKILL.md` in this package. After
 publication it is available at
-`https://unpkg.com/shopstack@0.2.1/SKILL.md` with the release-pinned package.
+`https://unpkg.com/shopstack@0.2.2/SKILL.md` with the release-pinned package.
 
 ## Connections
 
@@ -113,6 +113,12 @@ Then run:
 shopstack checkout run --file checkout.json
 ```
 
+The CLI prints the private owner live-view URL as soon as checkout creation
+succeeds. Do not redirect it into shared logs or expose it to a model. The page
+is view-only unless the model explicitly requests human assistance; while that
+request is active, one owner viewer can use **Take control** and **Return
+control**. **Stop** is always available and never approves payment.
+
 When no provider is selected, the checkout runs normally until the payment
 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
@@ -154,7 +160,11 @@ restart recovery and durable credential storage; never use browser storage.
 
 `runCheckout` returns at a required input if its corresponding callback is
 omitted. Final payment approval is never inferred from a message or from
-supplying a card.
+supplying a card. While the checkout is active, the CLI and client use a one-time
+checkout-scoped WebSocket capability for change notification and always fetches
+the canonical resource after a signal. It falls back to bounded revision-aware
+HTTP waiting, then to fixed polling when either newer transport is unavailable.
+Neither the API key nor WebSocket capability is placed in the socket URL.
 
 Set `SHOPSTACK_API_URL` to target a different Shopstack API and
 `SHOPSTACK_CONFIG_FILE` to relocate CLI profiles.

package/SKILL.md

@@ -109,12 +109,27 @@ shopstack checkout run --file checkout.json
 Or create with MCP, then call `poll_checkout`. Display these authoritative fields to the user when they change:
 
 - `status`: one of exactly `queued`, `started`, `help_required`, `approval_required`, `submitting`, `complete`, `failed`, `cancelled`;
+- `presentation_revision`: the monotonic revision for user-visible checkout state;
 - `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;
 - `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`.
+The CLI and JavaScript client subscribe with a one-time checkout-scoped
+WebSocket capability. Each valid notification means the presentation revision
+changed; the client then fetches the canonical checkout before displaying or
+acting on it. The notification is not checkout state truth and never grants
+payment authority. The capability belongs in the WebSocket subprotocol, never
+the URL, logs, model context, or messages. If WebSocket delivery is unavailable,
+the client falls back to bounded HTTP waiting and then fixed polling.
+
+MCP and manual integrations poll every two seconds for `queued`, `started`, and
+`submitting`; every five seconds for `help_required` and `approval_required`;
+stop at `complete`, `failed`, or `cancelled`.
+
+The optional `live_view_url` is a private owner-viewer capability. Show it only
+to the initiating user. Do not store it in browser storage, analytics, logs,
+model context, or ordinary messages.
 
 ## Respond at typed boundaries
 

package/bin/shopstack

@@ -5,6 +5,8 @@ import { runCli } from "../src/cli.js";
 try {
   await runCli(process.argv.slice(2));
 } catch (error) {
-  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+  process.stderr.write(
+    `${error instanceof Error ? error.message : String(error)}\n`,
+  );
   process.exitCode = 1;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "shopstack",
-  "version": "0.2.1",
-  "description": "Shopstack API client and command-line checkout tools.",
+  "version": "0.2.2",
+  "description": "Production Shopstack SDK and CLI for agentic checkout.",
   "type": "module",
   "exports": {
     ".": {
@@ -23,8 +23,12 @@
     "shopstack": "bin/shopstack"
   },
   "scripts": {
+    "check": "npm run format:check && npm run test:coverage",
+    "format:check": "prettier --check .",
     "shopstack": "node ./bin/shopstack",
-    "test": "node --test"
+    "test": "node --test test",
+    "test:coverage": "node --test --experimental-test-coverage test",
+    "prepublishOnly": "npm run check"
   },
   "engines": {
     "node": ">=18"
@@ -33,11 +37,27 @@
     "type": "git",
     "url": "git+https://github.com/jimbo132/shopstack-cli.git"
   },
+  "homepage": "https://github.com/jimbo132/shopstack-cli#readme",
+  "bugs": {
+    "url": "https://github.com/jimbo132/shopstack-cli/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "ws": "8.21.3"
+  },
   "license": "MIT",
   "keywords": [
     "shopstack",
     "cli",
     "checkout",
-    "payments"
-  ]
+    "payments",
+    "agentic-commerce",
+    "agents"
+  ],
+  "devDependencies": {
+    "prettier": "3.6.2"
+  }
 }

package/src/cli.js

@@ -4,26 +4,50 @@ import { createInterface } from "node:readline/promises";
 import { ShopstackClient } from "./client.js";
 import { ConfigStore } from "./config.js";
 
-const HELP = `Shopstack
+const VERSION = "0.2.2";
+
+const HELP = `Shopstack CLI ${VERSION}
+
+Usage:
+  shopstack <command> [options]
 
 Account setup:
   shopstack signup
+    # Create or resume an email-verified Personal or Developer profile.
   shopstack signup user --email EMAIL
+    # Create a Personal profile without interactive account-type prompts.
   shopstack signup developer --email EMAIL
+    # Create a Developer management profile without interactive prompts.
   shopstack signup resume SIGNUP_ID
+    # Resume a known pending email-verification flow.
   shopstack users create --external-id ID [--profile NAME]
+    # Create an independently scoped user from a Developer profile.
   shopstack profiles list
+    # List local profiles without printing their credentials.
   shopstack profiles use NAME
+    # Select the profile used by later commands.
 
 Payment connection:
   shopstack connect list
+    # Inspect payment connections for the active user profile.
   shopstack connect link
+    # Connect Link Agentic Wallet in the trusted browser flow.
 
 Checkout:
   shopstack checkout create --file checkout.json
+    # Create a checkout and return control immediately.
   shopstack checkout run --file checkout.json
+    # Create, monitor, and complete a checkout interactively.
   shopstack checkout get CHECKOUT_ID
+    # Read the canonical current checkout state.
   shopstack checkout cancel CHECKOUT_ID
+    # Cancel a checkout that has not reached a terminal state.
+
+Options:
+  -h, --help
+    # Show this command reference.
+  -v, --version
+    # Print the installed Shopstack CLI version.
 `;
 
 function parseOptions(args, allowed) {
@@ -164,11 +188,7 @@ function signupPersistence(configStore, profileName) {
     async completePending(state, result) {
       const pendingId = state.attemptId ?? state.signupId ?? state.id;
       if (typeof configStore.completePendingSignup === "function") {
-        await configStore.completePendingSignup(
-          pendingId,
-          profileName,
-          result,
-        );
+        await configStore.completePendingSignup(pendingId, profileName, result);
         return;
       }
       await saveVerifiedSignup(result, profileName, configStore);
@@ -201,13 +221,17 @@ async function reportSignupProgress(progress, stream) {
       stream.write("Signup expired. Start again to receive a new email.\n");
       return;
     case "rate_limited":
-      stream.write("Signup is rate-limited. Retry after the indicated delay.\n");
+      stream.write(
+        "Signup is rate-limited. Retry after the indicated delay.\n",
+      );
       return;
     case "conflict":
       stream.write("Signup retry state conflicted and was cleared.\n");
       return;
     case "retryable_failure":
-      stream.write("Signup paused after a retryable failure. Run signup again to resume.\n");
+      stream.write(
+        "Signup paused after a retryable failure. Run signup again to resume.\n",
+      );
       return;
     default:
       return;
@@ -216,7 +240,7 @@ async function reportSignupProgress(progress, stream) {
 
 async function activeClient(dependencies, requiredKind = "user") {
   const profile = await dependencies.configStore.activeProfile();
-  const environmentKey = process.env.SHOPSTACK_API_KEY;
+  const environmentKey = dependencies.env.SHOPSTACK_API_KEY;
   const apiKey = environmentKey || profile?.apiKey;
   const keyType = environmentKey ? requiredKind : profile?.keyType;
   if (!apiKey)
@@ -227,7 +251,7 @@ async function activeClient(dependencies, requiredKind = "user") {
   return {
     client: dependencies.clientFactory({
       apiKey,
-      baseUrl: process.env.SHOPSTACK_API_URL,
+      baseUrl: dependencies.env.SHOPSTACK_API_URL,
     }),
     profile,
   };
@@ -244,13 +268,23 @@ export async function runCli(args, supplied = {}) {
     stderr: process.stderr,
     stdin: process.stdin,
     stdout: process.stdout,
+    env: process.env,
     ...supplied,
   };
   const [group, action, ...rest] = args;
-  if (group === undefined || group === "help" || group === "--help") {
+  if (
+    group === undefined ||
+    group === "help" ||
+    group === "--help" ||
+    group === "-h"
+  ) {
     dependencies.stdout.write(HELP);
     return;
   }
+  if (group === "--version" || group === "-v") {
+    dependencies.stdout.write(`${VERSION}\n`);
+    return;
+  }
 
   if (group === "signup") {
     if (action === "resume") {
@@ -259,10 +293,12 @@ export async function runCli(args, supplied = {}) {
       }
       const pending = await dependencies.configStore.pendingSignup(rest[0]);
       if (pending === undefined) {
-        throw new Error("That signup is not present in the local profile store.");
+        throw new Error(
+          "That signup is not present in the local profile store.",
+        );
       }
       const client = dependencies.clientFactory({
-        baseUrl: process.env.SHOPSTACK_API_URL,
+        baseUrl: dependencies.env.SHOPSTACK_API_URL,
       });
       const result = await client.signup({
         accountType: pending.accountType,
@@ -286,14 +322,18 @@ export async function runCli(args, supplied = {}) {
       );
     }
     const signupArgs = action === undefined ? [] : rest;
-    const { options, positional } = parseOptions(signupArgs, new Set(["email", "profile"]));
+    const { options, positional } = parseOptions(
+      signupArgs,
+      new Set(["email", "profile"]),
+    );
     if (positional.length > 0) throw new Error("Unexpected signup argument.");
     const pendingCandidates =
       action === undefined &&
       typeof dependencies.configStore.pendingSignups === "function"
         ? await dependencies.configStore.pendingSignups()
         : [];
-    const resumable = pendingCandidates.length === 1 ? pendingCandidates[0] : undefined;
+    const resumable =
+      pendingCandidates.length === 1 ? pendingCandidates[0] : undefined;
     let accountType;
     let email;
     if (resumable !== undefined) {
@@ -301,12 +341,13 @@ export async function runCli(args, supplied = {}) {
       email = resumable.email;
       dependencies.stderr.write("Resuming pending signup.\n");
     } else if (action === undefined) {
-      email = String(
-        await visiblePrompt("Email: ", dependencies),
-      ).trim();
+      email = String(await visiblePrompt("Email: ", dependencies)).trim();
       if (email.length === 0) throw new Error("Email is required.");
       const selected = String(
-        await visiblePrompt("Account type (Personal / Developer): ", dependencies),
+        await visiblePrompt(
+          "Account type (Personal / Developer): ",
+          dependencies,
+        ),
       )
         .trim()
         .toLowerCase();
@@ -322,7 +363,7 @@ export async function runCli(args, supplied = {}) {
       email = required(options, "email");
     }
     const client = dependencies.clientFactory({
-      baseUrl: process.env.SHOPSTACK_API_URL,
+      baseUrl: dependencies.env.SHOPSTACK_API_URL,
     });
     const profileName =
       options.profile ??
@@ -373,10 +414,7 @@ export async function runCli(args, supplied = {}) {
           },
           { activate: true },
         );
-        writeJson(
-          dependencies.stdout,
-          sanitizedUserResult(user, externalId),
-        );
+        writeJson(dependencies.stdout, sanitizedUserResult(user, externalId));
       }
     }
     return;
@@ -454,6 +492,11 @@ export async function runCli(args, supplied = {}) {
     const { client } = await activeClient(dependencies, "user");
     const request = await dependencies.readJsonFile(required(options, "file"));
     const result = await client.runCheckout(request, {
+      onCreated: (checkout) => {
+        if (typeof checkout.live_view_url === "string") {
+          dependencies.stderr.write(`Live view: ${checkout.live_view_url}\n`);
+        }
+      },
       onProgress: (checkout) => {
         const intent =
           checkout.intent?.name === undefined
@@ -513,4 +556,4 @@ export async function runCli(args, supplied = {}) {
   throw new Error("Unknown command. Run `shopstack help`.");
 }
 
-export { HELP };
+export { HELP, VERSION };

package/src/client.d.ts

@@ -2,6 +2,7 @@ export interface ShopstackClientOptions {
   apiKey?: string;
   baseUrl?: string;
   fetch?: typeof fetch;
+  webSocket?: typeof WebSocket;
 }
 
 export interface PaymentCard {
@@ -33,6 +34,7 @@ export interface Checkout {
     | "failed"
     | "cancelled";
   revision: number;
+  presentation_revision: number;
   activity: string;
   intent?: {
     name: string;
@@ -40,6 +42,7 @@ export interface Checkout {
     updated_at: string;
   };
   item_url: string;
+  live_view_url?: string;
   required_input?: { type: "payment_card" };
   approval?: PaymentApproval;
   result?: Record<string, unknown>;
@@ -51,6 +54,7 @@ export interface Checkout {
 
 export interface RunCheckoutOptions {
   idempotencyKey?: string;
+  onCreated?(checkout: Checkout): void | Promise<void>;
   pollIntervalMs?: number;
   timeoutMs?: number;
   onProgress?(checkout: Checkout): void | Promise<void>;
@@ -66,6 +70,14 @@ export interface RunCheckoutOptions {
   ): string | Promise<string | undefined> | undefined;
 }
 
+export interface CheckoutUpdateSubscription {
+  socket_url: string;
+  protocol: "shopstack.v1";
+  token: string;
+  expires_at: string;
+  presentation_revision: number;
+}
+
 export interface AccountSignupStarted {
   id: string;
   account_type: "personal" | "developer";
@@ -93,9 +105,9 @@ export interface SignupOptions {
   timeoutMs?: number;
   persistence?: SignupPersistence;
   onProgress?(progress: SignupProgress): void | Promise<void>;
-  onVerificationRequired?(signup: Omit<AccountSignupStarted, "poll_token">):
-    | void
-    | Promise<void>;
+  onVerificationRequired?(
+    signup: Omit<AccountSignupStarted, "poll_token">,
+  ): void | Promise<void>;
 }
 
 export interface PendingSignupState {
@@ -156,9 +168,7 @@ export class ShopstackClient {
   pollAccountSignup(
     signupId: string,
     pollToken: string,
-  ): Promise<
-    Omit<AccountSignupStarted, "poll_token"> | VerifiedAccountSignup
-  >;
+  ): Promise<Omit<AccountSignupStarted, "poll_token"> | VerifiedAccountSignup>;
   waitForAccountSignup(
     signupId: string,
     pollToken: string,
@@ -190,6 +200,14 @@ export class ShopstackClient {
     options?: { idempotencyKey?: string },
   ): Promise<Checkout>;
   getCheckout(checkoutId: string): Promise<Checkout>;
+  createCheckoutUpdateSubscription(
+    checkoutId: string,
+  ): Promise<CheckoutUpdateSubscription>;
+  waitForCheckoutUpdate(
+    checkoutId: string,
+    afterRevision: number,
+    waitSeconds?: number,
+  ): Promise<Checkout | undefined>;
   cancelCheckout(
     checkoutId: string,
     options?: { idempotencyKey?: string },

package/src/client.js

@@ -1,4 +1,5 @@
 import { randomBytes, randomUUID } from "node:crypto";
+import WebSocket from "ws";
 
 const TERMINAL_STATUSES = new Set(["complete", "failed", "cancelled"]);
 
@@ -30,11 +31,119 @@ function delay(milliseconds) {
     : new Promise((resolve) => setTimeout(resolve, milliseconds));
 }
 
+function presentationRevision(checkout) {
+  return Number.isInteger(checkout?.presentation_revision)
+    ? checkout.presentation_revision
+    : checkout.revision;
+}
+
+class CheckoutUpdateWatcher {
+  constructor(client, checkoutId) {
+    this.client = client;
+    this.checkoutId = checkoutId;
+    this.latestRevision = 0;
+    this.waiter = undefined;
+    this.socket = undefined;
+    this.unavailable = typeof client.WebSocket !== "function";
+  }
+
+  async connect() {
+    if (this.socket || this.unavailable) return;
+    try {
+      const subscription = await this.client.createCheckoutUpdateSubscription(
+        this.checkoutId,
+      );
+      const socket = new this.client.WebSocket(subscription.socket_url, [
+        subscription.protocol,
+        subscription.token,
+      ]);
+      this.socket = socket;
+      socket.addEventListener("message", (event) => {
+        let payload;
+        try {
+          payload = JSON.parse(String(event.data));
+        } catch {
+          return;
+        }
+        if (
+          payload?.type !== "checkout_changed" ||
+          !Number.isInteger(payload.presentation_revision) ||
+          payload.presentation_revision < 1 ||
+          typeof payload.terminal !== "boolean"
+        ) {
+          return;
+        }
+        this.latestRevision = Math.max(
+          this.latestRevision,
+          payload.presentation_revision,
+        );
+        this.waiter?.();
+      });
+      const unavailable = () => {
+        this.unavailable = true;
+        this.waiter?.();
+      };
+      socket.addEventListener("error", unavailable);
+      socket.addEventListener("close", unavailable);
+    } catch {
+      this.unavailable = true;
+    }
+  }
+
+  async wait(afterRevision, timeoutMs) {
+    await this.connect();
+    if (this.latestRevision > afterRevision) return { kind: "changed" };
+    if (!this.unavailable) {
+      const changed = await new Promise((resolve) => {
+        let settled = false;
+        const settle = (value) => {
+          if (settled) return;
+          settled = true;
+          this.waiter = undefined;
+          clearTimeout(timer);
+          resolve(value);
+        };
+        this.waiter = () =>
+          settle(
+            this.latestRevision > afterRevision ? "changed" : "unavailable",
+          );
+        const timer = setTimeout(
+          () => settle("timeout"),
+          Math.max(1, Math.min(timeoutMs, 25_000)),
+        );
+      });
+      if (changed === "changed") return { kind: "changed" };
+      if (changed === "timeout") return { kind: "refresh" };
+    }
+    try {
+      const checkout = await this.client.waitForCheckoutUpdate(
+        this.checkoutId,
+        afterRevision,
+        Math.max(1, Math.min(25, Math.ceil(timeoutMs / 1_000))),
+      );
+      return checkout === undefined
+        ? { kind: "refresh" }
+        : { checkout, kind: "checkout" };
+    } catch {
+      return { kind: "unavailable" };
+    }
+  }
+
+  close() {
+    try {
+      this.socket?.close(1000, "Checkout monitoring complete");
+    } catch {
+      // Monitoring teardown must not alter the checkout result.
+    }
+  }
+}
+
 export class ShopstackClient {
   constructor({
     apiKey,
-    baseUrl = "https://shopstack-staging.shopstack.workers.dev/v1",
+    baseUrl = "https://api.shopstack.ai/v1",
     fetch: fetchImplementation = globalThis.fetch,
+    webSocket: webSocketImplementation = WebSocket,
   } = {}) {
     if (typeof baseUrl !== "string" || !/^https?:\/\//u.test(baseUrl)) {
       throw new TypeError("baseUrl must be an HTTP(S) URL");
@@ -45,6 +154,7 @@ export class ShopstackClient {
     this.apiKey = apiKey;
     this.baseUrl = baseUrl.replace(/\/+$/u, "");
     this.fetch = fetchImplementation;
+    this.WebSocket = webSocketImplementation;
   }
 
   async request(
@@ -98,7 +208,12 @@ export class ShopstackClient {
     return payload;
   }
 
-  _startAccountSignup({ accountType, email, idempotencyKey: key, recoveryKey }) {
+  _startAccountSignup({
+    accountType,
+    email,
+    idempotencyKey: key,
+    recoveryKey,
+  }) {
     return this.request("/accounts", {
       body: { account_type: accountType, email },
       idempotencyKey: key,
@@ -164,16 +279,14 @@ export class ShopstackClient {
       },
     };
     const publish = async (state, details = {}) => {
-      if (typeof onProgress === "function") await onProgress({ state, ...details });
+      if (typeof onProgress === "function")
+        await onProgress({ state, ...details });
     };
     let pending = await storage.loadPending({
       accountType,
       email: normalizedEmail,
     });
-    if (
-      pending?.expiresAt &&
-      Date.parse(pending.expiresAt) <= Date.now()
-    ) {
+    if (pending?.expiresAt && Date.parse(pending.expiresAt) <= Date.now()) {
       await storage.deletePending(pending);
       await publish("expired", {
         account_type: accountType,
@@ -331,6 +444,22 @@ export class ShopstackClient {
     return this.request(`/checkout/${encodeURIComponent(checkoutId)}`);
   }
 
+  createCheckoutUpdateSubscription(checkoutId) {
+    return this.request(`/checkout/${encodeURIComponent(checkoutId)}/updates`, {
+      method: "POST",
+    });
+  }
+
+  waitForCheckoutUpdate(checkoutId, afterRevision, waitSeconds = 25) {
+    const query = new URLSearchParams({
+      after: String(afterRevision),
+      wait: String(waitSeconds),
+    });
+    return this.request(
+      `/checkout/${encodeURIComponent(checkoutId)}/updates?${query.toString()}`,
+    );
+  }
+
   cancelCheckout(checkoutId, { idempotencyKey: key } = {}) {
     return this.request(`/checkout/${encodeURIComponent(checkoutId)}/cancel`, {
       idempotencyKey: key ?? idempotencyKey("cancel"),
@@ -396,12 +525,16 @@ export class ShopstackClient {
     let checkout = await this.createCheckout(checkoutRequest, {
       idempotencyKey: options.idempotencyKey,
     });
+    if (typeof options.onCreated === "function") {
+      await options.onCreated(checkout);
+    }
     let progressFingerprint;
     const publishProgress = async (current) => {
       if (typeof options.onProgress !== "function") return;
       const fingerprint = JSON.stringify([
         current.status,
         current.revision,
+        current.presentation_revision,
         current.activity,
         current.intent?.name,
         current.intent?.phase,
@@ -413,74 +546,88 @@ export class ShopstackClient {
       progressFingerprint = fingerprint;
       await options.onProgress(current);
     };
-    await publishProgress(checkout);
+    const watcher = new CheckoutUpdateWatcher(this, checkout.id);
     let handledPaymentRevision;
     let handledApprovalId;
     let handledMessageRevision;
-    while (!TERMINAL_STATUSES.has(checkout.status)) {
-      if (Date.now() - startedAt >= timeoutMs) {
-        throw new ShopstackApiError("Checkout monitoring timed out.", {
-          code: "checkout_timeout",
-        });
-      }
-      checkout = await this.getCheckout(checkout.id);
-      await publishProgress(checkout);
-      if (
-        checkout.required_input?.type === "payment_card" &&
-        handledPaymentRevision !== checkout.revision
-      ) {
-        if (typeof options.paymentDetails !== "function") return checkout;
-        handledPaymentRevision = checkout.revision;
-        const card = await options.paymentDetails(checkout);
-        if (card === undefined) return checkout;
-        await this.providePaymentDetails(checkout.id, card, {
-          idempotencyKey: `payment-details-${checkout.id}-${checkout.revision}`,
-        });
-        continue;
-      }
-      if (
-        checkout.status === "approval_required" &&
-        checkout.approval &&
-        handledApprovalId !== checkout.approval.id
-      ) {
-        if (typeof options.approve !== "function") return checkout;
-        handledApprovalId = checkout.approval.id;
-        const approved = await options.approve(checkout.approval, checkout);
-        if (typeof approved !== "boolean") return checkout;
-        await this.decidePaymentApproval(
-          checkout.id,
-          checkout.approval.id,
-          approved,
-          { idempotencyKey: `approval-${checkout.approval.id}` },
+    try {
+      while (true) {
+        await publishProgress(checkout);
+        if (TERMINAL_STATUSES.has(checkout.status)) return checkout;
+        const elapsed = Date.now() - startedAt;
+        if (elapsed >= timeoutMs) {
+          throw new ShopstackApiError("Checkout monitoring timed out.", {
+            code: "checkout_timeout",
+          });
+        }
+        if (
+          checkout.required_input?.type === "payment_card" &&
+          handledPaymentRevision !== checkout.revision
+        ) {
+          if (typeof options.paymentDetails !== "function") return checkout;
+          handledPaymentRevision = checkout.revision;
+          const card = await options.paymentDetails(checkout);
+          if (card === undefined) return checkout;
+          checkout = await this.providePaymentDetails(checkout.id, card, {
+            idempotencyKey: `payment-details-${checkout.id}-${checkout.revision}`,
+          });
+          handledMessageRevision = checkout.revision;
+          continue;
+        }
+        if (
+          checkout.status === "approval_required" &&
+          checkout.approval &&
+          handledApprovalId !== checkout.approval.id
+        ) {
+          if (typeof options.approve !== "function") return checkout;
+          handledApprovalId = checkout.approval.id;
+          const approved = await options.approve(checkout.approval, checkout);
+          if (typeof approved !== "boolean") return checkout;
+          checkout = await this.decidePaymentApproval(
+            checkout.id,
+            checkout.approval.id,
+            approved,
+            { idempotencyKey: `approval-${checkout.approval.id}` },
+          );
+          if (!approved) return checkout;
+          continue;
+        }
+        if (
+          checkout.status === "help_required" &&
+          checkout.required_input === undefined &&
+          handledMessageRevision !== checkout.revision
+        ) {
+          if (typeof options.message !== "function") return checkout;
+          handledMessageRevision = checkout.revision;
+          const content = await options.message(checkout);
+          if (typeof content !== "string" || content.length === 0)
+            return checkout;
+          await this.sendMessage(checkout.id, content, {
+            idempotencyKey: `message-${checkout.id}-${checkout.revision}`,
+          });
+          continue;
+        }
+        const remainingMs = timeoutMs - (Date.now() - startedAt);
+        const update = await watcher.wait(
+          presentationRevision(checkout),
+          remainingMs,
         );
-        if (!approved) return this.getCheckout(checkout.id);
-        continue;
-      }
-      if (
-        checkout.status === "help_required" &&
-        checkout.required_input === undefined &&
-        handledMessageRevision !== checkout.revision
-      ) {
-        if (typeof options.message !== "function") return checkout;
-        handledMessageRevision = checkout.revision;
-        const content = await options.message(checkout);
-        if (typeof content !== "string" || content.length === 0)
-          return checkout;
-        await this.sendMessage(checkout.id, content, {
-          idempotencyKey: `message-${checkout.id}-${checkout.revision}`,
-        });
-        continue;
-      }
-      if (!TERMINAL_STATUSES.has(checkout.status)) {
-        const pollIntervalMs =
-          options.pollIntervalMs ??
-          (checkout.status === "help_required" ||
-          checkout.status === "approval_required"
-            ? 5_000
-            : 2_000);
-        await delay(pollIntervalMs);
+        if (update.kind === "unavailable") {
+          const pollIntervalMs =
+            options.pollIntervalMs ??
+            (checkout.status === "help_required" ||
+            checkout.status === "approval_required"
+              ? 5_000
+              : 2_000);
+          await delay(Math.min(pollIntervalMs, remainingMs));
+        }
+        checkout =
+          update.kind === "checkout"
+            ? update.checkout
+            : await this.getCheckout(checkout.id);
       }
+    } finally {
+      watcher.close();
     }
-    return checkout;
   }
 }