shopstack 0.2.5 → 0.3.0

package/src/checkout-monitor.js

@@ -0,0 +1,126 @@
+// Notifications carry no checkout authority. The caller always reads the
+// authenticated canonical resource after this wait returns.
+export function checkoutMonitor(client, checkoutId, WebSocketImplementation) {
+  let attempted = false;
+  let socket;
+  let unavailable = typeof WebSocketImplementation !== "function";
+  let opened = false;
+  let latest = 0;
+  let delivered = 0;
+  let wake;
+  const close = () => {
+    unavailable = true;
+    const current = socket;
+    socket = undefined;
+    try {
+      current?.close();
+    } catch {
+      /* Already closed or never opened. */
+    }
+    wake?.();
+  };
+  const connect = async (remainingMs) => {
+    attempted = true;
+    try {
+      const subscription = await client.subscribeToCheckoutUpdates(checkoutId, {
+        signal: AbortSignal.timeout(Math.max(1, Math.min(5_000, remainingMs))),
+      });
+      const expected = new URL(
+        `${client.baseUrl}/checkout/${encodeURIComponent(checkoutId)}/updates`,
+      );
+      expected.protocol = expected.protocol === "https:" ? "wss:" : "ws:";
+      if (
+        subscription?.socket_url !== expected.href ||
+        subscription.protocol !== "shopstack.v1" ||
+        typeof subscription.token !== "string" ||
+        subscription.token.length > 4096 ||
+        !/^cus_v1\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/u.test(subscription.token) ||
+        !(Date.parse(subscription.expires_at) > Date.now())
+      ) {
+        unavailable = true;
+        return;
+      }
+      socket = new WebSocketImplementation(subscription.socket_url, [
+        subscription.protocol,
+        subscription.token,
+      ]);
+      latest = Number.isSafeInteger(subscription.presentation_revision)
+        ? subscription.presentation_revision
+        : 0;
+      socket.addEventListener("open", () => {
+        opened = true;
+      });
+      socket.addEventListener("close", close);
+      socket.addEventListener("error", close);
+      socket.addEventListener("message", (event) => {
+        if (typeof event.data !== "string" || event.data.length > 4096) return;
+        try {
+          const notification = JSON.parse(event.data);
+          if (
+            notification.type === "checkout_changed" &&
+            Number.isSafeInteger(notification.presentation_revision) &&
+            notification.presentation_revision > latest
+          ) {
+            latest = notification.presentation_revision;
+            wake?.();
+          }
+        } catch {
+          /* Malformed notifications cannot change checkout state. */
+        }
+      });
+    } catch (error) {
+      if (error?.status === 401 || error?.status === 403) throw error;
+      close();
+    }
+  };
+  return {
+    close,
+    async wait(after, remainingMs) {
+      const deadline = Date.now() + remainingMs;
+      if (!attempted && !unavailable) await connect(remainingMs);
+      const changed = () => latest > Math.max(after, delivered);
+      if (changed()) {
+        delivered = latest;
+        return;
+      }
+      if (!unavailable) {
+        await new Promise((resolve) => {
+          const finish = () => {
+            clearTimeout(timer);
+            wake = undefined;
+            resolve();
+          };
+          const timer = setTimeout(
+            () => {
+              if (!opened) close();
+              finish();
+            },
+            Math.max(
+              1,
+              Math.min(opened ? 25_000 : 5_000, deadline - Date.now()),
+            ),
+          );
+          wake = () => {
+            if (unavailable || changed()) finish();
+          };
+        });
+        if (!unavailable || changed()) {
+          delivered = latest;
+          return;
+        }
+      }
+      const remaining = deadline - Date.now();
+      if (remaining < 1_000) {
+        await new Promise((resolve) =>
+          setTimeout(resolve, Math.max(0, remaining)),
+        );
+        return;
+      }
+      await client.waitForCheckoutUpdate(checkoutId, {
+        after,
+        wait: Math.min(25, Math.floor(remaining / 1_000)),
+        signal: AbortSignal.timeout(remaining),
+      });
+    },
+  };
+}

package/src/cli.js

@@ -1,60 +1,40 @@
-import { spawn } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import { createInterface } from "node:readline/promises";
 
 import { ShopstackClient } from "./client.js";
-import { ConfigStore } from "./config.js";
+import { ConfigStore, resolveProfileBaseUrl } from "./config.js";
 
-const VERSION = JSON.parse(
-  await readFile(new URL("../package.json", import.meta.url), "utf8"),
-).version;
-const LINK_POLL_ATTEMPTS = 60;
-const LINK_POLL_INTERVAL_MS = 5_000;
-
-const HELP = `Shopstack CLI ${VERSION}
-
-Usage:
-  shopstack <command> [options]
+const HELP = `Shopstack
 
 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.
+
+Reservation:
+  shopstack reservation create --file reservation.json
+  shopstack reservation run --file reservation.json
+  shopstack reservation get RESERVATION_ID
+  shopstack reservation options RESERVATION_ID [--offset N] [--limit N]
+  shopstack reservation option RESERVATION_ID OPTION_ID
+  shopstack reservation message RESERVATION_ID --revision N --content TEXT
+  shopstack reservation cancel RESERVATION_ID --revision N
 
 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 view CHECKOUT_ID
-    # Replace and return the active checkout's private owner live-view URL.
+  shopstack checkout updates CHECKOUT_ID --after N [--wait SECONDS]
+  shopstack checkout live-view CHECKOUT_ID
   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) {
@@ -86,6 +66,26 @@ function required(options, name) {
   return value;
 }
 
+function requiredRevision(options) {
+  const value = Number(required(options, "revision"));
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw new Error("Option --revision must be a positive integer.");
+  }
+  return value;
+}
+
+function boundedIntegerOption(options, name, fallback, minimum, maximum) {
+  const raw = options[name];
+  if (raw === undefined) return fallback;
+  const value = Number(raw);
+  if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
+    throw new Error(
+      `Option --${name} must be an integer from ${minimum} through ${maximum}.`,
+    );
+  }
+  return value;
+}
+
 function isAffirmative(value) {
   const answer = String(value).trim().toLowerCase();
   return answer === "y" || answer === "yes";
@@ -95,77 +95,6 @@ function writeJson(stream, value) {
   stream.write(`${JSON.stringify(value, null, 2)}\n`);
 }
 
-function delay(milliseconds) {
-  return new Promise((resolve) => setTimeout(resolve, milliseconds));
-}
-
-async function openExternal(url) {
-  const parsed = new URL(url);
-  if (parsed.protocol !== "https:") {
-    throw new Error("Only HTTPS connection URLs can be opened.");
-  }
-  const [command, args] =
-    process.platform === "darwin"
-      ? ["open", [url]]
-      : process.platform === "win32"
-        ? ["cmd.exe", ["/d", "/s", "/c", "start", "", url]]
-        : ["xdg-open", [url]];
-  await new Promise((resolve, reject) => {
-    const child = spawn(command, args, { detached: true, stdio: "ignore" });
-    child.once("error", reject);
-    child.once("spawn", () => {
-      child.unref();
-      resolve();
-    });
-  });
-}
-
-async function connectLink(client, dependencies) {
-  let result = await client.connect("link");
-  if (
-    result.connection_status !== "action_required" ||
-    typeof result.connect_url !== "string"
-  ) {
-    return result;
-  }
-
-  dependencies.stderr.write(`Open Link: ${result.connect_url}\n`);
-  if (typeof result.phrase === "string") {
-    dependencies.stderr.write(`Confirmation phrase: ${result.phrase}\n`);
-  }
-  try {
-    await dependencies.openExternal(result.connect_url);
-  } catch {
-    dependencies.stderr.write(
-      "The browser could not open automatically. Open the URL shown above.\n",
-    );
-  }
-  dependencies.stderr.write("Waiting for Link confirmation...\n");
-
-  for (let attempt = 0; attempt < dependencies.linkPollAttempts; attempt += 1) {
-    await dependencies.delay(dependencies.linkPollIntervalMs);
-    result = await client.connect("link");
-    if (
-      result.connection_status === "active" &&
-      result.checkout_ready === true
-    ) {
-      dependencies.stderr.write("✓ Link connected\n");
-      return result;
-    }
-    if (
-      result.connection_status !== "action_required" &&
-      result.connection_status !== "connecting"
-    ) {
-      return result;
-    }
-  }
-
-  dependencies.stderr.write(
-    "Link setup is still pending. Run `shopstack connect link` to resume.\n",
-  );
-  return result;
-}
-
 async function readJsonFile(path) {
   return JSON.parse(await readFile(path, "utf8"));
 }
@@ -240,20 +169,21 @@ function sanitizedUserResult(result, profile) {
   return { api_key_saved: true, profile, user };
 }
 
-async function saveVerifiedSignup(result, profileName, configStore) {
+async function saveVerifiedSignup(result, profileName, configStore, baseUrl) {
   await configStore.saveProfile(
     profileName,
     {
       accountId: result.account.id,
       apiKey: result.api_key,
       keyType: result.key_type,
+      ...(baseUrl === undefined ? {} : { baseUrl }),
       ...(result.user?.id === undefined ? {} : { userId: result.user.id }),
     },
     { activate: true },
   );
 }
 
-function signupPersistence(configStore, profileName) {
+function signupPersistence(configStore, profileName, baseUrl) {
   return {
     async loadPending(input) {
       return typeof configStore.findPendingSignup === "function"
@@ -261,7 +191,11 @@ function signupPersistence(configStore, profileName) {
         : undefined;
     },
     async savePending(state) {
-      await configStore.savePendingSignup({ ...state, profile: profileName });
+      await configStore.savePendingSignup({
+        ...state,
+        ...(baseUrl === undefined ? {} : { baseUrl }),
+        profile: profileName,
+      });
     },
     async completePending(state, result) {
       const pendingId = state.attemptId ?? state.signupId ?? state.id;
@@ -269,7 +203,7 @@ function signupPersistence(configStore, profileName) {
         await configStore.completePendingSignup(pendingId, profileName, result);
         return;
       }
-      await saveVerifiedSignup(result, profileName, configStore);
+      await saveVerifiedSignup(result, profileName, configStore, baseUrl);
       await configStore.deletePendingSignup(pendingId);
     },
     async deletePending(state) {
@@ -316,9 +250,23 @@ async function reportSignupProgress(progress, stream) {
   }
 }
 
+function reportReservationTurn(reservation, stream) {
+  const turn = reservation.turn;
+  if (typeof turn?.message === "string") {
+    stream.write(`${turn.message}\n`);
+  }
+  const details =
+    turn?.locations ??
+    turn?.options ??
+    turn?.confirmation_prompt ??
+    turn?.confirmation ??
+    turn?.cancellation;
+  if (details !== undefined) writeJson(stream, details);
+}
+
 async function activeClient(dependencies, requiredKind = "user") {
   const profile = await dependencies.configStore.activeProfile();
-  const environmentKey = dependencies.env.SHOPSTACK_API_KEY;
+  const environmentKey = process.env.SHOPSTACK_API_KEY;
   const apiKey = environmentKey || profile?.apiKey;
   const keyType = environmentKey ? requiredKind : profile?.keyType;
   if (!apiKey)
@@ -329,7 +277,10 @@ async function activeClient(dependencies, requiredKind = "user") {
   return {
     client: dependencies.clientFactory({
       apiKey,
-      baseUrl: dependencies.env.SHOPSTACK_API_URL,
+      baseUrl: resolveProfileBaseUrl(
+        environmentKey ? undefined : profile,
+        process.env.SHOPSTACK_API_URL,
+      ),
     }),
     profile,
   };
@@ -340,33 +291,19 @@ export async function runCli(args, supplied = {}) {
     clientFactory: (options) => new ShopstackClient(options),
     configStore: new ConfigStore(),
     confirm: undefined,
-    delay,
-    linkPollAttempts: LINK_POLL_ATTEMPTS,
-    linkPollIntervalMs: LINK_POLL_INTERVAL_MS,
-    openExternal,
     prompt: undefined,
     readJsonFile,
     secretPrompt: undefined,
     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" ||
-    group === "-h"
-  ) {
+  if (group === undefined || group === "help" || group === "--help") {
     dependencies.stdout.write(HELP);
     return;
   }
-  if (group === "--version" || group === "-v") {
-    dependencies.stdout.write(`${VERSION}\n`);
-    return;
-  }
 
   if (group === "signup") {
     if (action === "resume") {
@@ -380,7 +317,7 @@ export async function runCli(args, supplied = {}) {
         );
       }
       const client = dependencies.clientFactory({
-        baseUrl: dependencies.env.SHOPSTACK_API_URL,
+        baseUrl: resolveProfileBaseUrl(pending, process.env.SHOPSTACK_API_URL),
       });
       const result = await client.signup({
         accountType: pending.accountType,
@@ -390,6 +327,7 @@ export async function runCli(args, supplied = {}) {
         persistence: signupPersistence(
           dependencies.configStore,
           pending.profile,
+          client.baseUrl ?? pending.baseUrl,
         ),
       });
       writeJson(dependencies.stdout, {
@@ -445,7 +383,7 @@ export async function runCli(args, supplied = {}) {
       email = required(options, "email");
     }
     const client = dependencies.clientFactory({
-      baseUrl: dependencies.env.SHOPSTACK_API_URL,
+      baseUrl: resolveProfileBaseUrl(resumable, process.env.SHOPSTACK_API_URL),
     });
     const profileName =
       options.profile ??
@@ -456,7 +394,11 @@ export async function runCli(args, supplied = {}) {
       email,
       onProgress: (progress) =>
         reportSignupProgress(progress, dependencies.stderr),
-      persistence: signupPersistence(dependencies.configStore, profileName),
+      persistence: signupPersistence(
+        dependencies.configStore,
+        profileName,
+        client.baseUrl ?? resumable?.baseUrl,
+      ),
     });
     writeJson(dependencies.stdout, {
       ...sanitizedAccountResult(result),
@@ -492,6 +434,9 @@ export async function runCli(args, supplied = {}) {
             accountId: profile.accountId,
             apiKey: user.api_key,
             keyType: "user",
+            ...(profile.baseUrl === undefined
+              ? {}
+              : { baseUrl: profile.baseUrl }),
             userId: user.id,
           },
           { activate: true },
@@ -518,6 +463,7 @@ export async function runCli(args, supplied = {}) {
         accountId: profile.accountId,
         apiKey: result.api_key,
         keyType: "user",
+        ...(profile.baseUrl === undefined ? {} : { baseUrl: profile.baseUrl }),
         userId: result.id,
       },
       { activate: true },
@@ -552,7 +498,124 @@ export async function runCli(args, supplied = {}) {
     const result =
       action === "list"
         ? await client.listConnections()
-        : await connectLink(client, dependencies);
+        : await client.connect("link");
+    writeJson(dependencies.stdout, result);
+    return;
+  }
+
+  if (group === "reservation" && action === "create") {
+    const { options, positional } = parseOptions(rest, new Set(["file"]));
+    if (positional.length > 0) {
+      throw new Error("Unexpected reservation argument.");
+    }
+    const { client } = await activeClient(dependencies, "user");
+    const result = await client.createReservation(
+      await dependencies.readJsonFile(required(options, "file")),
+    );
+    writeJson(dependencies.stdout, result);
+    return;
+  }
+
+  if (group === "reservation" && action === "run") {
+    const { options, positional } = parseOptions(rest, new Set(["file"]));
+    if (positional.length > 0) {
+      throw new Error("Unexpected reservation argument.");
+    }
+    const { client } = await activeClient(dependencies, "user");
+    const request = await dependencies.readJsonFile(required(options, "file"));
+    const result = await client.runReservation(request, {
+      onTurn: (reservation) =>
+        reportReservationTurn(reservation, dependencies.stderr),
+      respond: async (reservation) => {
+        if (reservation.status === "confirmation_required") {
+          const accepted = dependencies.confirm
+            ? await dependencies.confirm(
+                reservation.turn?.confirmation_prompt,
+                reservation,
+              )
+            : isAffirmative(
+                await visiblePrompt(
+                  "Confirm this exact booking? [y/N] ",
+                  dependencies,
+                ),
+              );
+          return accepted
+            ? "Yes, confirm this exact booking."
+            : "No, do not book this reservation.";
+        }
+        return String(await visiblePrompt("Your reply: ", dependencies)).trim();
+      },
+    });
+    writeJson(dependencies.stdout, result);
+    return;
+  }
+
+  if (group === "reservation" && action === "get") {
+    if (rest.length !== 1) throw new Error("A reservation ID is required.");
+    const { client } = await activeClient(dependencies, "user");
+    writeJson(dependencies.stdout, await client.getReservation(rest[0]));
+    return;
+  }
+
+  if (group === "reservation" && action === "options") {
+    const { options, positional } = parseOptions(
+      rest,
+      new Set(["limit", "offset"]),
+    );
+    if (positional.length !== 1) {
+      throw new Error("A reservation ID is required.");
+    }
+    const { client } = await activeClient(dependencies, "user");
+    writeJson(
+      dependencies.stdout,
+      await client.listReservationOptions(positional[0], {
+        limit: boundedIntegerOption(options, "limit", 6, 1, 6),
+        offset: boundedIntegerOption(options, "offset", 0, 0, 29),
+      }),
+    );
+    return;
+  }
+
+  if (group === "reservation" && action === "option") {
+    if (rest.length !== 2) {
+      throw new Error("A reservation ID and option ID are required.");
+    }
+    const { client } = await activeClient(dependencies, "user");
+    writeJson(
+      dependencies.stdout,
+      await client.getReservationOption(rest[0], rest[1]),
+    );
+    return;
+  }
+
+  if (group === "reservation" && action === "message") {
+    const { options, positional } = parseOptions(
+      rest,
+      new Set(["content", "revision"]),
+    );
+    if (positional.length !== 1) {
+      throw new Error("A reservation ID is required.");
+    }
+    const { client } = await activeClient(dependencies, "user");
+    const result = await client.sendReservationMessage(
+      positional[0],
+      required(options, "content"),
+      requiredRevision(options),
+    );
+    writeJson(dependencies.stdout, result);
+    return;
+  }
+
+  if (group === "reservation" && action === "cancel") {
+    const { options, positional } = parseOptions(rest, new Set(["revision"]));
+    if (positional.length !== 1) {
+      throw new Error("A reservation ID is required.");
+    }
+    const { client } = await activeClient(dependencies, "user");
+    const result = await client.cancelReservation(
+      positional[0],
+      requiredRevision(options),
+    );
     writeJson(dependencies.stdout, result);
     return;
   }
@@ -574,11 +637,6 @@ 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
@@ -624,18 +682,50 @@ export async function runCli(args, supplied = {}) {
     return;
   }
 
-  if (
-    group === "checkout" &&
-    (action === "get" || action === "view" || action === "cancel")
-  ) {
+  if (group === "checkout" && action === "updates") {
+    const { options, positional } = parseOptions(
+      rest,
+      new Set(["after", "wait"]),
+    );
+    if (positional.length !== 1) throw new Error("A checkout ID is required.");
+    required(options, "after");
+    const after = boundedIntegerOption(
+      options,
+      "after",
+      undefined,
+      0,
+      Number.MAX_SAFE_INTEGER,
+    );
+    const wait = boundedIntegerOption(options, "wait", 25, 1, 25);
+    const { client } = await activeClient(dependencies, "user");
+    writeJson(
+      dependencies.stdout,
+      (await client.waitForCheckoutUpdate(positional[0], { after, wait })) ?? {
+        unchanged: true,
+      },
+    );
+    return;
+  }
+
+  if (group === "checkout" && action === "live-view") {
+    const { positional } = parseOptions(rest, new Set());
+    if (positional.length !== 1) throw new Error("A checkout ID is required.");
+    const { client } = await activeClient(dependencies, "user");
+    const result = await client.createLiveView(positional[0]);
+    dependencies.stderr.write(
+      "This replacement invalidates previous live-view links and viewer sessions.\n",
+    );
+    writeJson(dependencies.stdout, result);
+    return;
+  }
+
+  if (group === "checkout" && (action === "get" || action === "cancel")) {
     if (rest.length !== 1) throw new Error("A checkout ID is required.");
     const { client } = await activeClient(dependencies, "user");
     const result =
       action === "get"
         ? await client.getCheckout(rest[0])
-        : action === "view"
-          ? await client.createLiveView(rest[0])
-          : await client.cancelCheckout(rest[0]);
+        : await client.cancelCheckout(rest[0]);
     writeJson(dependencies.stdout, result);
     return;
   }
@@ -643,4 +733,4 @@ export async function runCli(args, supplied = {}) {
   throw new Error("Unknown command. Run `shopstack help`.");
 }
 
-export { HELP, VERSION };
+export { HELP };