shopstack 0.2.6 → 0.3.0

package/src/cli.js

@@ -1,54 +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 login [--email EMAIL] [--profile NAME] [--account-type personal|developer]
-    # Log in, or create the requested account type when the email is new.
+  shopstack signup
+  shopstack signup user --email EMAIL
+  shopstack signup developer --email EMAIL
+  shopstack signup resume SIGNUP_ID
   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) {
@@ -80,79 +66,33 @@ function required(options, name) {
   return value;
 }
 
-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.");
+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.");
   }
-  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();
-    });
-  });
+  return value;
 }
 
-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",
+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}.`,
     );
   }
-  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;
-    }
-  }
+  return value;
+}
 
-  dependencies.stderr.write(
-    "Link setup is still pending. Run `shopstack connect link` to resume.\n",
-  );
-  return result;
+function isAffirmative(value) {
+  const answer = String(value).trim().toLowerCase();
+  return answer === "y" || answer === "yes";
+}
+
+function writeJson(stream, value) {
+  stream.write(`${JSON.stringify(value, null, 2)}\n`);
 }
 
 async function readJsonFile(path) {
@@ -229,47 +169,52 @@ function sanitizedUserResult(result, profile) {
   return { api_key_saved: true, profile, user };
 }
 
-async function saveVerifiedLogin(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 loginPersistence(configStore, profileName) {
+function signupPersistence(configStore, profileName, baseUrl) {
   return {
     async loadPending(input) {
-      return typeof configStore.findPendingLogin === "function"
-        ? configStore.findPendingLogin(input)
+      return typeof configStore.findPendingSignup === "function"
+        ? configStore.findPendingSignup(input)
         : undefined;
     },
     async savePending(state) {
-      await configStore.savePendingLogin({ ...state, profile: profileName });
+      await configStore.savePendingSignup({
+        ...state,
+        ...(baseUrl === undefined ? {} : { baseUrl }),
+        profile: profileName,
+      });
     },
     async completePending(state, result) {
-      const pendingId = state.attemptId ?? state.loginId ?? state.id;
-      if (typeof configStore.completePendingLogin === "function") {
-        await configStore.completePendingLogin(pendingId, profileName, result);
+      const pendingId = state.attemptId ?? state.signupId ?? state.id;
+      if (typeof configStore.completePendingSignup === "function") {
+        await configStore.completePendingSignup(pendingId, profileName, result);
         return;
       }
-      await saveVerifiedLogin(result, profileName, configStore);
-      await configStore.deletePendingLogin(pendingId);
+      await saveVerifiedSignup(result, profileName, configStore, baseUrl);
+      await configStore.deletePendingSignup(pendingId);
     },
     async deletePending(state) {
-      await configStore.deletePendingLogin(
-        state.attemptId ?? state.loginId ?? state.id,
+      await configStore.deletePendingSignup(
+        state.attemptId ?? state.signupId ?? state.id,
       );
     },
   };
 }
 
-async function reportLoginProgress(progress, stream) {
+async function reportSignupProgress(progress, stream) {
   switch (progress.state) {
     case "email_sent":
       stream.write("Verification email sent.\n");
@@ -281,21 +226,23 @@ async function reportLoginProgress(progress, stream) {
       stream.write("✓ Email verified\n");
       return;
     case "complete":
-      stream.write("✓ Shopstack login complete\n");
+      stream.write("✓ Shopstack account created\n");
       stream.write("✓ Credentials saved securely\n");
       return;
     case "expired":
-      stream.write("Login expired. Start again to receive a new email.\n");
+      stream.write("Signup expired. Start again to receive a new email.\n");
       return;
     case "rate_limited":
-      stream.write("Login 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("Login retry state conflicted and was cleared.\n");
+      stream.write("Signup retry state conflicted and was cleared.\n");
       return;
     case "retryable_failure":
       stream.write(
-        "Login paused after a retryable failure. Run login again to resume.\n",
+        "Signup paused after a retryable failure. Run signup again to resume.\n",
       );
       return;
     default:
@@ -303,19 +250,37 @@ async function reportLoginProgress(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) throw new Error("No active Shopstack API key. Run login first.");
+  if (!apiKey)
+    throw new Error("No active Shopstack API key. Run signup first.");
   if (requiredKind && keyType !== requiredKind) {
     throw new Error(`This command requires an active ${requiredKind} profile.`);
   }
   return {
     client: dependencies.clientFactory({
       apiKey,
-      baseUrl: dependencies.env.SHOPSTACK_API_URL,
+      baseUrl: resolveProfileBaseUrl(
+        environmentKey ? undefined : profile,
+        process.env.SHOPSTACK_API_URL,
+      ),
     }),
     profile,
   };
@@ -326,90 +291,158 @@ 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 === "login") {
+  if (group === "signup") {
+    if (action === "resume") {
+      if (rest.length !== 1) {
+        throw new Error("Use `shopstack signup resume SIGNUP_ID`.");
+      }
+      const pending = await dependencies.configStore.pendingSignup(rest[0]);
+      if (pending === undefined) {
+        throw new Error(
+          "That signup is not present in the local profile store.",
+        );
+      }
+      const client = dependencies.clientFactory({
+        baseUrl: resolveProfileBaseUrl(pending, process.env.SHOPSTACK_API_URL),
+      });
+      const result = await client.signup({
+        accountType: pending.accountType,
+        email: pending.email,
+        onProgress: (progress) =>
+          reportSignupProgress(progress, dependencies.stderr),
+        persistence: signupPersistence(
+          dependencies.configStore,
+          pending.profile,
+          client.baseUrl ?? pending.baseUrl,
+        ),
+      });
+      writeJson(dependencies.stdout, {
+        ...sanitizedAccountResult(result),
+        profile: pending.profile,
+      });
+      return;
+    }
+    if (action !== undefined && action !== "user" && action !== "developer") {
+      throw new Error(
+        "Use `shopstack signup user` or `shopstack signup developer`.",
+      );
+    }
+    const signupArgs = action === undefined ? [] : rest;
     const { options, positional } = parseOptions(
-      args.slice(1),
-      new Set(["account-type", "email", "profile"]),
+      signupArgs,
+      new Set(["email", "profile"]),
     );
-    if (positional.length > 0) throw new Error("Unexpected login argument.");
-    const profileName = options.profile ?? "default";
-    const requestedAccountType = options["account-type"] ?? "personal";
-    if (
-      requestedAccountType !== "personal" &&
-      requestedAccountType !== "developer"
-    ) {
-      throw new Error("Account type must be personal or developer.");
-    }
+    if (positional.length > 0) throw new Error("Unexpected signup argument.");
     const pendingCandidates =
-      typeof dependencies.configStore.pendingLogins === "function"
-        ? await dependencies.configStore.pendingLogins()
+      action === undefined &&
+      typeof dependencies.configStore.pendingSignups === "function"
+        ? await dependencies.configStore.pendingSignups()
         : [];
-    const matchingPending = pendingCandidates.filter(
-      (pending) =>
-        pending.profile === profileName &&
-        (options.email === undefined ||
-          pending.email.trim().toLowerCase() ===
-            options.email.trim().toLowerCase()) &&
-        (options["account-type"] === undefined ||
-          pending.accountType === requestedAccountType),
-    );
     const resumable =
-      matchingPending.length === 1 ? matchingPending[0] : undefined;
-    const accountType = resumable?.accountType ?? requestedAccountType;
-    let email = resumable?.email ?? options.email;
+      pendingCandidates.length === 1 ? pendingCandidates[0] : undefined;
+    let accountType;
+    let email;
     if (resumable !== undefined) {
-      dependencies.stderr.write("Resuming pending login.\n");
-    }
-    if (email === undefined) {
+      accountType = resumable.accountType;
+      email = resumable.email;
+      dependencies.stderr.write("Resuming pending signup.\n");
+    } else if (action === undefined) {
       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,
+        ),
+      )
+        .trim()
+        .toLowerCase();
+      if (selected === "personal" || selected === "user") {
+        accountType = "personal";
+      } else if (selected === "developer") {
+        accountType = "developer";
+      } else {
+        throw new Error("Account type must be Personal or Developer.");
+      }
+    } else {
+      accountType = action === "user" ? "personal" : "developer";
+      email = required(options, "email");
     }
-    if (email.length === 0) throw new Error("Email is required.");
     const client = dependencies.clientFactory({
-      baseUrl: dependencies.env.SHOPSTACK_API_URL,
+      baseUrl: resolveProfileBaseUrl(resumable, process.env.SHOPSTACK_API_URL),
     });
-    const result = await client.login({
+    const profileName =
+      options.profile ??
+      resumable?.profile ??
+      (accountType === "developer" ? "developer" : "default");
+    const result = await client.signup({
       accountType,
       email,
       onProgress: (progress) =>
-        reportLoginProgress(progress, dependencies.stderr),
-      persistence: loginPersistence(dependencies.configStore, profileName),
+        reportSignupProgress(progress, dependencies.stderr),
+      persistence: signupPersistence(
+        dependencies.configStore,
+        profileName,
+        client.baseUrl ?? resumable?.baseUrl,
+      ),
     });
     writeJson(dependencies.stdout, {
       ...sanitizedAccountResult(result),
       profile: profileName,
     });
-    if (result.key_type === "developer") {
+    if (accountType === "developer") {
       dependencies.stderr.write(
         "The developer management credential cannot run user checkouts. Create a user profile with `shopstack users create --external-id ID`.\n",
       );
+      if (
+        action === undefined &&
+        isAffirmative(
+          await visiblePrompt(
+            "Create the first developer-owned user now? (y/N): ",
+            dependencies,
+          ),
+        )
+      ) {
+        const externalId = String(
+          await visiblePrompt("User external ID: ", dependencies),
+        ).trim();
+        if (externalId.length === 0) {
+          throw new Error("User external ID is required.");
+        }
+        const { client: developerClient, profile } = await activeClient(
+          dependencies,
+          "developer",
+        );
+        const user = await developerClient.createUser({ externalId });
+        await dependencies.configStore.saveProfile(
+          externalId,
+          {
+            accountId: profile.accountId,
+            apiKey: user.api_key,
+            keyType: "user",
+            ...(profile.baseUrl === undefined
+              ? {}
+              : { baseUrl: profile.baseUrl }),
+            userId: user.id,
+          },
+          { activate: true },
+        );
+        writeJson(dependencies.stdout, sanitizedUserResult(user, externalId));
+      }
     }
     return;
   }
@@ -430,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 },
@@ -464,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;
   }
@@ -486,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
@@ -536,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;
   }
@@ -555,4 +733,4 @@ export async function runCli(args, supplied = {}) {
   throw new Error("Unknown command. Run `shopstack help`.");
 }
 
-export { HELP, VERSION };
+export { HELP };