shopstack 0.1.0 → 0.2.1

package/src/cli.js

@@ -0,0 +1,516 @@
+import { readFile } from "node:fs/promises";
+import { createInterface } from "node:readline/promises";
+
+import { ShopstackClient } from "./client.js";
+import { ConfigStore } from "./config.js";
+
+const HELP = `Shopstack
+
+Account setup:
+  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]
+  shopstack profiles list
+  shopstack profiles use NAME
+
+Payment connection:
+  shopstack connect list
+  shopstack connect link
+
+Checkout:
+  shopstack checkout create --file checkout.json
+  shopstack checkout run --file checkout.json
+  shopstack checkout get CHECKOUT_ID
+  shopstack checkout cancel CHECKOUT_ID
+`;
+
+function parseOptions(args, allowed) {
+  const positional = [];
+  const options = {};
+  for (let index = 0; index < args.length; index += 1) {
+    const value = args[index];
+    if (!value.startsWith("--")) {
+      positional.push(value);
+      continue;
+    }
+    const name = value.slice(2);
+    if (!allowed.has(name)) throw new Error(`Unknown option: --${name}`);
+    const optionValue = args[index + 1];
+    if (optionValue === undefined || optionValue.startsWith("--")) {
+      throw new Error(`Option --${name} requires a value.`);
+    }
+    options[name] = optionValue;
+    index += 1;
+  }
+  return { options, positional };
+}
+
+function required(options, name) {
+  const value = options[name];
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`Missing required option: --${name}`);
+  }
+  return value;
+}
+
+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) {
+  return JSON.parse(await readFile(path, "utf8"));
+}
+
+async function visiblePrompt(message, dependencies) {
+  if (dependencies.prompt) return dependencies.prompt(message);
+  const input = dependencies.stdin ?? process.stdin;
+  const output = dependencies.stdout ?? process.stdout;
+  const interface_ = createInterface({ input, output });
+  try {
+    return await interface_.question(message);
+  } finally {
+    interface_.close();
+  }
+}
+
+async function hiddenPrompt(message, dependencies) {
+  if (dependencies.secretPrompt) return dependencies.secretPrompt(message);
+  const input = dependencies.stdin ?? process.stdin;
+  const output = dependencies.stderr ?? process.stderr;
+  if (!input.isTTY || typeof input.setRawMode !== "function") {
+    throw new Error(
+      "Protected payment input requires an interactive terminal.",
+    );
+  }
+  output.write(message);
+  return new Promise((resolve, reject) => {
+    let value = "";
+    const restore = () => {
+      input.off("data", onData);
+      input.setRawMode(false);
+      input.pause();
+      output.write("\n");
+    };
+    const onData = (chunk) => {
+      const text = String(chunk);
+      for (const character of text) {
+        if (character === "\r" || character === "\n") {
+          restore();
+          resolve(value);
+          return;
+        }
+        if (character === "\u0003") {
+          restore();
+          reject(new Error("Payment input cancelled."));
+          return;
+        }
+        if (character === "\u007f" || character === "\b") {
+          value = value.slice(0, -1);
+        } else {
+          value += character;
+        }
+      }
+    };
+    input.setRawMode(true);
+    input.resume();
+    input.on("data", onData);
+  });
+}
+
+function sanitizedAccountResult(result) {
+  return {
+    account: result.account,
+    api_key_saved: true,
+    key_type: result.key_type,
+    ...(result.user === undefined ? {} : { user: result.user }),
+  };
+}
+
+function sanitizedUserResult(result, profile) {
+  const { api_key: _apiKey, ...user } = result;
+  return { api_key_saved: true, profile, user };
+}
+
+async function saveVerifiedSignup(result, profileName, configStore) {
+  await configStore.saveProfile(
+    profileName,
+    {
+      accountId: result.account.id,
+      apiKey: result.api_key,
+      keyType: result.key_type,
+      ...(result.user?.id === undefined ? {} : { userId: result.user.id }),
+    },
+    { activate: true },
+  );
+}
+
+function signupPersistence(configStore, profileName) {
+  return {
+    async loadPending(input) {
+      return typeof configStore.findPendingSignup === "function"
+        ? configStore.findPendingSignup(input)
+        : undefined;
+    },
+    async savePending(state) {
+      await configStore.savePendingSignup({ ...state, profile: profileName });
+    },
+    async completePending(state, result) {
+      const pendingId = state.attemptId ?? state.signupId ?? state.id;
+      if (typeof configStore.completePendingSignup === "function") {
+        await configStore.completePendingSignup(
+          pendingId,
+          profileName,
+          result,
+        );
+        return;
+      }
+      await saveVerifiedSignup(result, profileName, configStore);
+      await configStore.deletePendingSignup(pendingId);
+    },
+    async deletePending(state) {
+      await configStore.deletePendingSignup(
+        state.attemptId ?? state.signupId ?? state.id,
+      );
+    },
+  };
+}
+
+async function reportSignupProgress(progress, stream) {
+  switch (progress.state) {
+    case "email_sent":
+      stream.write("Verification email sent.\n");
+      return;
+    case "waiting":
+      stream.write("Waiting for verification...\n");
+      return;
+    case "verified":
+      stream.write("✓ Email verified\n");
+      return;
+    case "complete":
+      stream.write("✓ Shopstack account created\n");
+      stream.write("✓ Credentials saved securely\n");
+      return;
+    case "expired":
+      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");
+      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");
+      return;
+    default:
+      return;
+  }
+}
+
+async function activeClient(dependencies, requiredKind = "user") {
+  const profile = await dependencies.configStore.activeProfile();
+  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 signup first.");
+  if (requiredKind && keyType !== requiredKind) {
+    throw new Error(`This command requires an active ${requiredKind} profile.`);
+  }
+  return {
+    client: dependencies.clientFactory({
+      apiKey,
+      baseUrl: process.env.SHOPSTACK_API_URL,
+    }),
+    profile,
+  };
+}
+
+export async function runCli(args, supplied = {}) {
+  const dependencies = {
+    clientFactory: (options) => new ShopstackClient(options),
+    configStore: new ConfigStore(),
+    confirm: undefined,
+    prompt: undefined,
+    readJsonFile,
+    secretPrompt: undefined,
+    stderr: process.stderr,
+    stdin: process.stdin,
+    stdout: process.stdout,
+    ...supplied,
+  };
+  const [group, action, ...rest] = args;
+  if (group === undefined || group === "help" || group === "--help") {
+    dependencies.stdout.write(HELP);
+    return;
+  }
+
+  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: 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,
+        ),
+      });
+      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(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;
+    let accountType;
+    let email;
+    if (resumable !== 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");
+    }
+    const client = dependencies.clientFactory({
+      baseUrl: process.env.SHOPSTACK_API_URL,
+    });
+    const profileName =
+      options.profile ??
+      resumable?.profile ??
+      (accountType === "developer" ? "developer" : "default");
+    const result = await client.signup({
+      accountType,
+      email,
+      onProgress: (progress) =>
+        reportSignupProgress(progress, dependencies.stderr),
+      persistence: signupPersistence(dependencies.configStore, profileName),
+    });
+    writeJson(dependencies.stdout, {
+      ...sanitizedAccountResult(result),
+      profile: profileName,
+    });
+    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",
+            userId: user.id,
+          },
+          { activate: true },
+        );
+        writeJson(
+          dependencies.stdout,
+          sanitizedUserResult(user, externalId),
+        );
+      }
+    }
+    return;
+  }
+
+  if (group === "users" && action === "create") {
+    const { options, positional } = parseOptions(
+      rest,
+      new Set(["external-id", "profile"]),
+    );
+    if (positional.length > 0) throw new Error("Unexpected user argument.");
+    const externalId = required(options, "external-id");
+    const { client, profile } = await activeClient(dependencies, "developer");
+    const result = await client.createUser({ externalId });
+    const profileName = options.profile ?? externalId;
+    await dependencies.configStore.saveProfile(
+      profileName,
+      {
+        accountId: profile.accountId,
+        apiKey: result.api_key,
+        keyType: "user",
+        userId: result.id,
+      },
+      { activate: true },
+    );
+    writeJson(dependencies.stdout, sanitizedUserResult(result, profileName));
+    return;
+  }
+
+  if (group === "profiles" && action === "list") {
+    const config = await dependencies.configStore.load();
+    writeJson(dependencies.stdout, {
+      active: config.active,
+      profiles: Object.entries(config.profiles).map(([name, profile]) => ({
+        account_id: profile.accountId,
+        key_type: profile.keyType,
+        name,
+        ...(profile.userId === undefined ? {} : { user_id: profile.userId }),
+      })),
+    });
+    return;
+  }
+  if (group === "profiles" && action === "use") {
+    if (rest.length !== 1) throw new Error("A profile name is required.");
+    await dependencies.configStore.useProfile(rest[0]);
+    writeJson(dependencies.stdout, { active: rest[0] });
+    return;
+  }
+
+  if (group === "connect" && (action === "list" || action === "link")) {
+    if (rest.length > 0) throw new Error("Unexpected connection argument.");
+    const { client } = await activeClient(dependencies, "user");
+    const result =
+      action === "list"
+        ? await client.listConnections()
+        : await client.connect("link");
+    writeJson(dependencies.stdout, result);
+    return;
+  }
+
+  if (group === "checkout" && action === "create") {
+    const { options, positional } = parseOptions(rest, new Set(["file"]));
+    if (positional.length > 0) throw new Error("Unexpected checkout argument.");
+    const { client } = await activeClient(dependencies, "user");
+    const result = await client.createCheckout(
+      await dependencies.readJsonFile(required(options, "file")),
+    );
+    writeJson(dependencies.stdout, result);
+    return;
+  }
+
+  if (group === "checkout" && action === "run") {
+    const { options, positional } = parseOptions(rest, new Set(["file"]));
+    if (positional.length > 0) throw new Error("Unexpected checkout argument.");
+    const { client } = await activeClient(dependencies, "user");
+    const request = await dependencies.readJsonFile(required(options, "file"));
+    const result = await client.runCheckout(request, {
+      onProgress: (checkout) => {
+        const intent =
+          checkout.intent?.name === undefined
+            ? ""
+            : ` ${checkout.intent.name}:${checkout.intent.phase}`;
+        dependencies.stderr.write(
+          `[${checkout.status}]${intent} ${checkout.activity ?? ""}`.trimEnd() +
+            "\n",
+        );
+      },
+      approve: async (approval) => {
+        const summary = [
+          `Subtotal: ${approval.subtotal ?? "unavailable"} ${approval.currency}`,
+          `Shipping: ${approval.shipping ?? "unavailable"} ${approval.currency}`,
+          `Tax: ${approval.tax ?? "unavailable"} ${approval.currency}`,
+          `Total: ${approval.total} ${approval.currency}`,
+        ].join("\n");
+        dependencies.stderr.write(`${summary}\n`);
+        if (dependencies.confirm) return dependencies.confirm(approval);
+        const answer = await visiblePrompt(
+          "Approve this exact payment? [y/N] ",
+          dependencies,
+        );
+        return /^y(?:es)?$/iu.test(answer.trim());
+      },
+      message: (checkout) =>
+        visiblePrompt(
+          `${checkout.activity || "Shopstack needs more information"}: `,
+          dependencies,
+        ),
+      paymentDetails: async () => ({
+        number: await hiddenPrompt("Card number: ", dependencies),
+        exp_month: Number(
+          await hiddenPrompt("Expiry month (1-12): ", dependencies),
+        ),
+        exp_year: Number(
+          await hiddenPrompt("Expiry year (YYYY): ", dependencies),
+        ),
+        cvc: await hiddenPrompt("CVC: ", dependencies),
+      }),
+    });
+    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])
+        : await client.cancelCheckout(rest[0]);
+    writeJson(dependencies.stdout, result);
+    return;
+  }
+
+  throw new Error("Unknown command. Run `shopstack help`.");
+}
+
+export { HELP };